{ "openapi": "3.1.0", "info": { "title": "UnifAPI", "version": "0.0.1", "description": "Unified, AI-friendly API for public-data providers. Single source of truth for the UnifAPI gateway — consumed by docs (Fumadocs), the marketing site, and downstream SDK generators.", "contact": { "name": "UnifAPI", "url": "https://unifapi.com", "email": "support@unifapi.com" }, "license": { "name": "Proprietary", "url": "https://unifapi.com/legal/terms-of-service" } }, "servers": [ { "url": "https://api.unifapi.com", "description": "Production" } ], "externalDocs": { "url": "https://docs.unifapi.com", "description": "UnifAPI developer documentation" }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "bilibili", "description": "Public-data Bilibili endpoints (Web surface). Path keys use numeric `uid` for users and `bv_id` (the URL slug, e.g. `BV1Bo4y1y79G`) for videos." }, { "name": "instagram", "description": "Public-data Instagram endpoints (V3 surface). Path keys use the URL-visible slugs (`username` for users, `shortcode` for posts). `/users/{username}` and `/posts/{shortcode}/comments/{commentId}/replies` cost two upstream calls — see ADR 0006 / ADR 0007 Rule 7. `media_id` and `user_id` are surfaced on responses so callers can cache the mapping." }, { "name": "kuaishou", "description": "Public-data Kuaishou / 快手 endpoints (App surface). Path keys use opaque `user_id` for users and `photo_id` for videos." }, { "name": "lemon8", "description": "Public-data Lemon8 endpoints (App surface). Path keys use numeric `user_id` for users and `item_id` for posts." }, { "name": "linkedin", "description": "Public-data LinkedIn endpoints. Path keys use LinkedIn URL slugs (`public_identifier` for users, `universal_name` for companies). Some sub-resources incur two upstream calls to resolve the URL slug into LinkedIn's internal URN / numeric id — see ADR 0006." }, { "name": "pipixia", "description": "Public-data PiPiXia / 皮皮虾 endpoints (App surface). Path keys use numeric `user_id` for users and `cell_id` for posts." }, { "name": "reddit", "description": "Public-data Reddit endpoints (APP surface). Path keys use `username` for users, `subreddit_name` for subreddits, and `post_id` (the `t3_*` fullname) for posts." }, { "name": "threads", "description": "Public-data Threads endpoints (Web surface). Path keys use `username` for users and `post_id` for posts." }, { "name": "tiktok", "description": "Public-data TikTok endpoints. All identity-shaped responses use the canonical Video / User / Comment / Music / Hashtag / LiveRoom shapes." }, { "name": "twitter", "description": "Public-data Twitter / X endpoints (Web surface). Path keys use `screen_name` (URL handle, without `@`) for users and `tweet_id` for tweets. The numeric user `id` (`rest_id`) is surfaced on responses for callers that need it." }, { "name": "weibo", "description": "Public-data Weibo endpoints (Web-V2 surface). Path keys use numeric `uid` for users and numeric `id` for posts." }, { "name": "xiaohongshu", "description": "Public-data Xiaohongshu / 小红书 endpoints (Web-V3 surface). Path keys use 24-character hex `user_id` for users and `note_id` for notes. Note detail and comments additionally require an `xsec_token` query param (returned by upstream alongside `note_id`)." }, { "name": "youtube", "description": "Public-data YouTube endpoints (Web surface). Path keys use `channel_id` for channels and `video_id` for videos." }, { "name": "zhihu", "description": "Public-data Zhihu / 知乎 endpoints (Web surface). Path keys use `user_url_token` (URL slug, e.g. `excited-vczh`) for users and numeric ids for questions / answers / articles." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "UnifAPI API key (forwarded verbatim as the upstream provider token)." } }, "schemas": { "Error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "validation_error", "invalid_id", "unauthorized", "not_found", "rate_limited", "internal_error", "response_shape_error", "upstream_error", "upstream_unavailable" ], "description": "Closed vocabulary — see docs/adr/0003-error-model.md." }, "message": { "type": "string" }, "request_id": { "type": "string", "description": "Provider-prefixed upstream id, e.g. `tikhub-`." }, "issues": { "type": "array", "items": {}, "description": "Present only when type=validation_error." } }, "required": [ "type", "message" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "required": [ "error" ], "description": "Standard gateway error envelope (ADR 0003)." }, "BilibiliDynamic": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Bilibili dynamic id (numeric string)." }, "type": { "type": "string", "description": "Upstream `DYNAMIC_TYPE_*` enum (raw)." }, "text": { "type": "string", "description": "Best-effort plain text content extracted from the dynamic's modules." }, "author": { "type": [ "object", "null" ], "properties": { "uid": { "type": "string" }, "name": { "type": "string" }, "avatar_url": { "type": "string" } }, "required": [ "uid", "name", "avatar_url" ] } }, "required": [ "id", "type", "text", "author" ] }, "BilibiliHotSearch": { "type": "object", "properties": { "keyword": { "type": "string" }, "show_name": { "type": "string" }, "icon_url": { "type": "string" }, "heat_score": { "type": "number" } }, "required": [ "keyword", "show_name", "icon_url", "heat_score" ] }, "BilibiliVideoPreview": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "bv_id": { "type": "string" }, "aid": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "duration": { "type": "string", "description": "Original `length` string from upstream (e.g. `12:34`)." }, "cover_url": { "type": "string" }, "author_uid": { "type": "string" }, "author_name": { "type": "string" }, "created_at": { "type": "number" }, "view_count": { "type": "number" } }, "required": [ "id", "bv_id", "aid", "title", "description", "duration", "cover_url", "author_uid", "author_name", "created_at", "view_count" ] }, "BilibiliUserRelationStat": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "uid": { "type": "string" }, "following_count": { "type": "number" }, "follower_count": { "type": "number" }, "whisper_count": { "type": "number" }, "blocked_count": { "type": "number" } }, "required": [ "id", "uid", "following_count", "follower_count", "whisper_count", "blocked_count" ] }, "BilibiliVideo": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Bilibili video URL slug (`BVxxxxx`)." }, "bv_id": { "type": "string" }, "aid": { "type": "string", "description": "Bilibili internal numeric video id." }, "title": { "type": "string" }, "description": { "type": "string" }, "duration_seconds": { "type": "number" }, "cover_url": { "type": "string" }, "published_at": { "type": "number", "description": "Unix-seconds publication timestamp." }, "view_count": { "type": "number" }, "danmaku_count": { "type": "number" }, "reply_count": { "type": "number" }, "favorite_count": { "type": "number" }, "like_count": { "type": "number" }, "share_count": { "type": "number" }, "coin_count": { "type": "number" }, "owner": { "type": [ "object", "null" ], "properties": { "uid": { "type": "string" }, "name": { "type": "string" }, "avatar_url": { "type": "string" } }, "required": [ "uid", "name", "avatar_url" ] } }, "required": [ "id", "bv_id", "aid", "title", "description", "duration_seconds", "cover_url", "published_at", "view_count", "danmaku_count", "reply_count", "favorite_count", "like_count", "share_count", "coin_count", "owner" ] }, "InstagramCarouselItem": { "type": "object", "properties": { "media_type": { "type": "number", "description": "1 = image, 2 = video" }, "image_url": { "type": "string" }, "video_url": { "type": "string" }, "accessibility_caption": { "type": [ "string", "null" ] } }, "required": [ "media_type", "image_url", "video_url", "accessibility_caption" ] }, "InstagramUserPreview": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "minLength": 1 }, "user_id": { "type": "string" }, "username": { "type": "string" }, "full_name": { "type": "string" }, "is_verified": { "type": "boolean" }, "is_private": { "type": "boolean" }, "profile_pic_url": { "type": "string" } }, "required": [ "id", "user_id", "username", "full_name", "is_verified", "is_private", "profile_pic_url" ], "description": "Lightweight Instagram user shape returned inside lists (followers, post authors, comment authors). Lacks counts; call /users/{id} for the full profile." }, "InstagramLocationLite": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] } }, "required": [ "id", "name", "lat", "lng" ], "description": "Compact location reference embedded in posts and nearby lists." }, "InstagramPost": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Instagram URL slug (`shortcode`). Path parameter for /instagram/posts/{id}/... endpoints." }, "shortcode": { "type": "string" }, "media_id": { "type": "string", "description": "Numeric upstream pk; surfaced so callers can skip the shortcode → media_id stitch when calling sub-resources." }, "media_type": { "type": "number", "description": "Upstream media_type: 1 = image, 2 = video, 8 = carousel" }, "product_type": { "type": "string", "description": "Upstream product_type: 'feed' (image/photo), 'clips' (reel), 'carousel_container', 'igtv', etc." }, "taken_at": { "type": "number", "description": "Unix-seconds timestamp." }, "caption": { "type": "string" }, "accessibility_caption": { "type": [ "string", "null" ] }, "image_url": { "type": "string", "description": "Largest available preview image (cover, for video/carousel)." }, "video_url": { "type": "string", "description": "Highest-quality video URL when applicable; empty string otherwise." }, "like_count": { "type": "number" }, "comment_count": { "type": "number" }, "play_count": { "type": "number", "description": "Video plays. 0 for non-video media." }, "view_count": { "type": "number", "description": "Reel/video views (separate from plays on IG side). 0 when N/A." }, "is_paid_partnership": { "type": "boolean" }, "has_audio": { "type": "boolean" }, "carousel_count": { "type": "number", "description": "Number of carousel items, or 0 if not a carousel." }, "carousel": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramCarouselItem" }, "description": "Carousel items when media_type === 8; empty array otherwise." }, "user": { "$ref": "#/components/schemas/InstagramUserPreview" }, "location": { "$ref": "#/components/schemas/InstagramLocationLite" } }, "required": [ "id", "shortcode", "media_id", "media_type", "product_type", "taken_at", "caption", "accessibility_caption", "image_url", "video_url", "like_count", "comment_count", "play_count", "view_count", "is_paid_partnership", "has_audio", "carousel_count", "carousel", "user", "location" ], "description": "Canonical Instagram post / reel. `id` is the URL shortcode; `media_id` is the numeric pk required by certain upstream sub-resources." }, "InstagramLocation": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "category": { "type": "string" }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] }, "city": { "type": "string" }, "address": { "type": "string" }, "phone": { "type": "string" }, "media_count": { "type": "number" } }, "required": [ "id", "name", "category", "lat", "lng", "city", "address", "phone", "media_count" ], "description": "Instagram location profile (full). `id` is the numeric upstream `location_id`." }, "InstagramComment": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "user": { "$ref": "#/components/schemas/InstagramUserPreview" }, "text": { "type": "string" }, "created_at": { "type": "number" }, "like_count": { "type": "number" }, "child_comment_count": { "type": "number" }, "has_translation": { "type": "boolean" }, "has_liked": { "type": "boolean" }, "parent_comment_id": { "type": [ "string", "null" ] } }, "required": [ "id", "user", "text", "created_at", "like_count", "child_comment_count", "has_translation", "has_liked", "parent_comment_id" ] }, "InstagramFormerUsername": { "type": "object", "properties": { "username": { "type": "string" }, "changed_at": { "type": "number", "description": "Unix-seconds timestamp of the change, 0 when upstream omits it." } }, "required": [ "username", "changed_at" ] }, "InstagramHighlight": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Highlight reel id, e.g. `highlight:18223279177302854`." }, "title": { "type": "string" }, "cover_url": { "type": "string" } }, "required": [ "id", "title", "cover_url" ], "description": "Instagram highlight reel metadata. Story contents are not surfaced because upstream's `get_highlight_stories` returned no story payload on probe (2026-05-20)." }, "InstagramUser": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Instagram URL slug (`username`). Path parameter for every /instagram/users/{id}/... endpoint." }, "user_id": { "type": "string", "minLength": 1, "description": "Numeric Instagram internal id (`pk`). Stable across username changes; some upstream sub-resources need it (gateway stitches automatically)." }, "username": { "type": "string" }, "full_name": { "type": "string" }, "is_verified": { "type": "boolean" }, "is_private": { "type": "boolean" }, "profile_pic_url": { "type": "string" }, "follower_count": { "type": "number" }, "following_count": { "type": "number" }, "media_count": { "type": "number" }, "fbid_v2": { "type": [ "string", "null" ], "description": "Cross-platform Facebook id, when present." } }, "required": [ "id", "user_id", "username", "full_name", "is_verified", "is_private", "profile_pic_url", "follower_count", "following_count", "media_count", "fbid_v2" ], "description": "Canonical Instagram user profile. `id` is the URL slug (`username`); `user_id` is the numeric pk used internally by some upstream sub-resources — surfaced so callers can avoid re-stitching." }, "KuaishouHotBoard": { "type": "object", "properties": { "board_id": { "type": "string" }, "board_name": { "type": "string" }, "type": { "type": "string" }, "banner_url": { "type": "string" } }, "required": [ "board_id", "board_name", "type", "banner_url" ] }, "KuaishouHotPerson": { "type": "object", "properties": { "user_id": { "type": "string" }, "user_name": { "type": "string" }, "avatar_url": { "type": "string" }, "rank": { "type": "number" } }, "required": [ "user_id", "user_name", "avatar_url", "rank" ] }, "KuaishouVideo": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "photo_id": { "type": "string" }, "caption": { "type": "string" }, "timestamp": { "type": "number", "description": "Unix-ms timestamp (passed through)." }, "cover_url": { "type": "string" }, "video_url": { "type": "string" }, "like_count": { "type": "number" }, "comment_count": { "type": "number" }, "share_count": { "type": "number" }, "user_id": { "type": "string" }, "user_name": { "type": "string" } }, "required": [ "id", "photo_id", "caption", "timestamp", "cover_url", "video_url", "like_count", "comment_count", "share_count", "user_id", "user_name" ] }, "KuaishouUser": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "user_id": { "type": "string" }, "kwai_id": { "type": "string" }, "user_name": { "type": "string" }, "avatar_url": { "type": "string" }, "description": { "type": "string" }, "gender": { "type": "string" }, "follower_count": { "type": "number" }, "following_count": { "type": "number" }, "photo_count": { "type": "number" }, "like_count": { "type": "number" }, "is_verified": { "type": "boolean" } }, "required": [ "id", "user_id", "kwai_id", "user_name", "avatar_url", "description", "gender", "follower_count", "following_count", "photo_count", "like_count", "is_verified" ] }, "KuaishouComment": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "timestamp": { "type": "number" }, "like_count": { "type": "number" }, "sub_comment_count": { "type": "number" }, "user_id": { "type": "string" }, "avatar_url": { "type": "string" } }, "required": [ "id", "content", "timestamp", "like_count", "sub_comment_count", "user_id", "avatar_url" ] }, "Lemon8HotKeyword": { "type": "object", "properties": { "keyword": { "type": "string" }, "pos": { "type": "number" } }, "required": [ "keyword", "pos" ] }, "Lemon8User": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "user_id": { "type": "string" }, "name": { "type": "string" }, "handle": { "type": "string", "description": "URL handle (`user_unique_name`)." }, "description": { "type": "string" }, "avatar_url": { "type": "string" }, "background_url": { "type": "string" }, "followers_count": { "type": "number" }, "following_count": { "type": "number" }, "posts_count": { "type": "number" }, "notes_count": { "type": "number" } }, "required": [ "id", "user_id", "name", "handle", "description", "avatar_url", "background_url", "followers_count", "following_count", "posts_count", "notes_count" ] }, "LinkedinAd": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "ad_url": { "type": "string" }, "image_url": { "type": "string" }, "ad_type": { "type": "string" }, "paid_for_by": { "type": [ "string", "null" ] }, "advertiser": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "name", "url" ] }, "publisher": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "name", "url" ] } }, "required": [ "id", "content", "ad_url", "image_url", "ad_type", "paid_for_by", "advertiser", "publisher" ] }, "LinkedinAffiliatedPage": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "universal_name": { "type": [ "string", "null" ] }, "linkedin_url": { "type": "string" }, "type": { "type": "string" }, "speciality": { "type": [ "string", "null" ] }, "follower_count": { "type": "integer" }, "logo_url": { "type": "string" } }, "required": [ "id", "name", "universal_name", "linkedin_url", "type", "speciality", "follower_count", "logo_url" ] }, "LinkedinJobCount": { "type": "object", "properties": { "total": { "type": "integer" } }, "required": [ "total" ] }, "LinkedinCompanyRef": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "url": { "type": "string" }, "logo_url": { "type": "string" } }, "required": [ "id", "name", "url", "logo_url" ], "description": "Compact reference to a company, embedded in jobs and experience records." }, "LinkedinJobListing": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "job_url": { "type": "string" }, "listed_at": { "type": [ "string", "null" ] }, "is_promoted": { "type": "boolean" }, "is_easy_apply": { "type": "boolean" }, "location": { "type": "string" }, "company": { "allOf": [ { "$ref": "#/components/schemas/LinkedinCompanyRef" }, { "type": "object", "properties": { "is_verified": { "type": "boolean" } }, "required": [ "is_verified" ] } ], "description": "Compact reference to a company, embedded in jobs and experience records." } }, "required": [ "id", "title", "job_url", "listed_at", "is_promoted", "is_easy_apply", "location", "company" ], "description": "Compact job record used in /companies/{id}/jobs and /search/jobs." }, "LinkedinMemberInsight": { "type": "object", "properties": { "title": { "type": "string" }, "insights": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "name", "count" ] } } }, "required": [ "title", "insights" ], "description": "Aggregated employee insight returned by /companies/{id}/member-insights. Each insight is one row of a stat table (e.g. \"Locations\" → [{name: 'Redmond, WA', count: 12345}])." }, "LinkedinUserPreview": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "urn": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "headline": { "type": "string" }, "location": { "type": "string" }, "avatar_url": { "type": "string" }, "url": { "type": "string" }, "is_verified": { "type": "boolean" }, "is_premium": { "type": "boolean" }, "is_top_voice": { "type": "boolean" }, "is_open_to_work": { "type": "boolean" }, "is_hiring": { "type": "boolean" }, "follower_count": { "type": [ "integer", "null" ], "description": "Present in company employee listings, null in plain search results." } }, "required": [ "id", "urn", "username", "display_name", "headline", "location", "avatar_url", "url", "is_verified", "is_premium", "is_top_voice", "is_open_to_work", "is_hiring", "follower_count" ], "description": "Compact user record used in search results and listing endpoints. `id` is the URL slug when known; otherwise the numeric LinkedIn user id." }, "LinkedinPostAuthor": { "type": "object", "properties": { "id": { "type": "string" }, "urn": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "headline": { "type": "string" }, "url": { "type": "string" }, "avatar_url": { "type": "string" }, "account_type": { "type": "string" }, "follower_count": { "type": [ "integer", "null" ] } }, "required": [ "id", "urn", "username", "display_name", "headline", "url", "avatar_url", "account_type", "follower_count" ], "description": "Heterogeneous post author — may be a person or a company. `username` is non-null only for people." }, "LinkedinPost": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "share_urn": { "type": "string" }, "post_type": { "type": "string", "description": "ugc | activity | share | ..." }, "text": { "type": "string" }, "url": { "type": "string" }, "create_time": { "type": "integer", "description": "Unix epoch seconds" }, "created_at": { "type": "string", "description": "Original ISO timestamp" }, "like_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "type", "count" ] } }, "author": { "$ref": "#/components/schemas/LinkedinPostAuthor" }, "content": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Pass-through LinkedIn post body block (images, video, document, article, celebration, poll, event). LinkedIn's structure for each is complex and evolving — kept as-is rather than reshaped." } }, "required": [ "id", "share_urn", "post_type", "text", "url", "create_time", "created_at", "like_count", "comment_count", "share_count", "reactions", "author", "content" ] }, "LinkedinEmployeeCountRange": { "type": "object", "properties": { "start": { "type": [ "integer", "null" ] }, "end": { "type": [ "integer", "null" ] } }, "required": [ "start", "end" ] }, "LinkedinHeadquarters": { "type": "object", "properties": { "country": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "address_line": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] } }, "required": [ "country", "city", "state", "address_line", "postal_code" ] }, "LinkedinCompany": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "URL slug (LinkedIn's `universal_name`). Use this for every /linkedin/companies/{id}/... endpoint." }, "company_id": { "type": "string", "minLength": 1, "description": "Numeric LinkedIn-internal id. Exposed because LinkedIn pages and ad-library URLs reference it; not needed for any /linkedin/* call." }, "name": { "type": "string" }, "description": { "type": "string" }, "website_url": { "type": [ "string", "null" ] }, "linkedin_url": { "type": "string" }, "is_verified": { "type": "boolean" }, "is_active": { "type": "boolean" }, "follower_count": { "type": "integer" }, "employee_count": { "type": "integer" }, "employee_count_range": { "$ref": "#/components/schemas/LinkedinEmployeeCountRange" }, "industries": { "type": "array", "items": { "type": "string" } }, "specialities": { "type": "array", "items": { "type": "string" } }, "headquarters": { "$ref": "#/components/schemas/LinkedinHeadquarters" }, "logo_url": { "type": "string" }, "cover_image_url": { "type": "string" }, "hashtags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "follower_count": { "type": "integer" } }, "required": [ "name", "follower_count" ] } } }, "required": [ "id", "company_id", "name", "description", "website_url", "linkedin_url", "is_verified", "is_active", "follower_count", "employee_count", "employee_count_range", "industries", "specialities", "headquarters", "logo_url", "cover_image_url", "hashtags" ] }, "LinkedinGroup": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "rules": { "type": "string" }, "member_count": { "type": "integer" }, "is_public": { "type": "boolean" }, "cover_image_url": { "type": "string" }, "logo_url": { "type": "string" } }, "required": [ "id", "name", "description", "rules", "member_count", "is_public", "cover_image_url", "logo_url" ] }, "LinkedinJobSalary": { "type": "object", "properties": { "min": { "type": [ "string", "null" ] }, "max": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "pay_period": { "type": [ "string", "null" ] }, "is_present": { "type": "boolean" } }, "required": [ "min", "max", "currency", "pay_period", "is_present" ] }, "LinkedinJobCompany": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "universal_name": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "description": { "type": "string" }, "follower_count": { "type": "integer" }, "staff_count": { "type": "integer" }, "industries": { "type": "array", "items": { "type": "string" } }, "logo_url": { "type": "string" } }, "required": [ "id", "name", "universal_name", "url", "description", "follower_count", "staff_count", "industries", "logo_url" ] }, "LinkedinJob": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "description": { "type": "string" }, "job_url": { "type": "string" }, "location": { "type": "string" }, "location_geocode": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "level": { "type": [ "string", "null" ] }, "employment_type": { "type": [ "string", "null" ] }, "is_new": { "type": "boolean" }, "view_count": { "type": "integer" }, "apply_count": { "type": "integer" }, "salary": { "$ref": "#/components/schemas/LinkedinJobSalary" }, "is_remote_allowed": { "type": "boolean" }, "listed_at": { "type": [ "string", "null" ] }, "original_listed_at": { "type": [ "string", "null" ] }, "expire_at": { "type": [ "string", "null" ] }, "industries": { "type": "array", "items": { "type": "string" } }, "job_functions": { "type": "array", "items": { "type": "string" } }, "benefits": { "type": "array", "items": { "type": "string" } }, "workplace_types": { "type": "array", "items": { "type": "string" } }, "company": { "$ref": "#/components/schemas/LinkedinJobCompany" } }, "required": [ "id", "title", "description", "job_url", "location", "location_geocode", "country_code", "state", "level", "employment_type", "is_new", "view_count", "apply_count", "salary", "is_remote_allowed", "listed_at", "original_listed_at", "expire_at", "industries", "job_functions", "benefits", "workplace_types", "company" ] }, "LinkedinComment": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "urn": { "type": "string" }, "text": { "type": "string" }, "create_time": { "type": "integer" }, "created_at": { "type": "string" }, "like_count": { "type": "integer" }, "reply_count": { "type": "integer" }, "is_pinned": { "type": "boolean" }, "is_edited": { "type": "boolean" }, "is_author": { "type": "boolean" }, "has_previous_replies": { "type": "boolean" }, "previous_replies_token": { "type": [ "string", "null" ] }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "type", "count" ] } }, "commenter": { "type": "object", "properties": { "id": { "type": "string" }, "display_name": { "type": "string" }, "headline": { "type": "string" }, "url": { "type": "string" }, "avatar_url": { "type": "string" } }, "required": [ "id", "display_name", "headline", "url", "avatar_url" ] } }, "required": [ "id", "urn", "text", "create_time", "created_at", "like_count", "reply_count", "is_pinned", "is_edited", "is_author", "has_previous_replies", "previous_replies_token", "reactions", "commenter" ] }, "LinkedinAdListing": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "advertiser": { "type": "string" }, "content_preview": { "type": "string" }, "ad_url": { "type": "string" }, "image_url": { "type": "string" } }, "required": [ "id", "advertiser", "content_preview", "ad_url", "image_url" ] }, "LinkedinSearchIndustry": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "LinkedinSearchLocation": { "type": "object", "properties": { "name": { "type": "string" }, "geocode": { "type": "string" } }, "required": [ "name", "geocode" ] }, "LinkedinSearchPost": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "url": { "type": "string" }, "title": { "type": "string" }, "create_time": { "type": "integer" }, "created_at": { "type": "string" }, "like_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "author": { "type": "object", "properties": { "display_name": { "type": "string" }, "headline": { "type": "string" }, "url": { "type": "string" } }, "required": [ "display_name", "headline", "url" ] } }, "required": [ "id", "url", "title", "create_time", "created_at", "like_count", "comment_count", "share_count", "author" ] }, "LinkedinSchool": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "universal_name": { "type": [ "string", "null" ] }, "location": { "type": "string" }, "student_count_display": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "logo_url": { "type": "string" } }, "required": [ "id", "name", "universal_name", "location", "student_count_display", "url", "logo_url" ] }, "LinkedinAbout": { "type": "object", "properties": { "joined": { "type": [ "string", "null" ] }, "contact_information": { "type": [ "string", "null" ] }, "profile_photo": { "type": [ "string", "null" ] } }, "required": [ "joined", "contact_information", "profile_photo" ], "description": "Free-form recency strings displayed on a LinkedIn profile (\"joined May 2013\", \"updated less than 3 months ago\"). Upstream gives no machine-readable form." }, "LinkedinCertification": { "type": "object", "properties": { "title": { "type": "string" }, "issued_by": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "credential_url": { "type": [ "string", "null" ] } }, "required": [ "title", "issued_by", "issued_at", "credential_url" ] }, "LinkedinUserComment": { "type": "object", "properties": { "urn": { "type": "string" }, "text": { "type": "string" }, "create_time": { "type": "integer" }, "created_at": { "type": "string" }, "like_count": { "type": "integer" }, "reply_count": { "type": "integer" }, "is_edited": { "type": "boolean" }, "post": { "allOf": [ { "$ref": "#/components/schemas/LinkedinPost" }, { "type": [ "object", "null" ] } ] } }, "required": [ "urn", "text", "create_time", "created_at", "like_count", "reply_count", "is_edited", "post" ], "description": "A comment authored by the target user on someone else's post. Returned by /users/{id}/comments." }, "LinkedinContactInfo": { "type": "object", "properties": { "urn": { "type": "string" }, "public_identifier": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "websites": { "type": "array", "items": { "type": "string" } }, "phone_numbers": { "type": "array", "items": { "type": "string" } }, "twitter": { "type": "array", "items": { "type": "string" } }, "address": { "type": [ "string", "null" ] }, "wechat": { "type": [ "string", "null" ] } }, "required": [ "urn", "public_identifier", "first_name", "last_name", "websites", "phone_numbers", "twitter", "address", "wechat" ] }, "LinkedinDateRange": { "type": "object", "properties": { "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ] } }, "required": [ "start", "end" ] }, "LinkedinEducation": { "type": "object", "properties": { "id": { "type": "string" }, "school": { "type": "string" }, "degree": { "type": [ "string", "null" ] }, "grade": { "type": [ "string", "null" ] }, "date": { "$ref": "#/components/schemas/LinkedinDateRange" } }, "required": [ "id", "school", "degree", "grade", "date" ] }, "LinkedinExperience": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "location": { "type": [ "string", "null" ] }, "employment_type": { "type": [ "string", "null" ] }, "date": { "$ref": "#/components/schemas/LinkedinDateRange" }, "company": { "$ref": "#/components/schemas/LinkedinCompanyRef" } }, "required": [ "title", "description", "location", "employment_type", "date", "company" ] }, "LinkedinFollowerStats": { "type": "object", "properties": { "follower_count": { "type": "integer" }, "connection_count": { "type": "integer" } }, "required": [ "follower_count", "connection_count" ] }, "LinkedinHonor": { "type": "object", "properties": { "title": { "type": "string" }, "issued_by": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "associated_with": { "type": [ "string", "null" ] } }, "required": [ "title", "issued_by", "issued_at", "associated_with" ] }, "LinkedinUserImage": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "image_urls": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string" } }, "required": [ "id", "url", "image_urls", "created_at" ] }, "LinkedinInterestCompany": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "follower_count": { "type": "integer" }, "url": { "type": "string" }, "logo_url": { "type": "string" } }, "required": [ "id", "name", "follower_count", "url", "logo_url" ] }, "LinkedinInterestGroup": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "logo_url": { "type": "string" } }, "required": [ "id", "name", "url", "logo_url" ] }, "LinkedinPublication": { "type": "object", "properties": { "title": { "type": "string" }, "publication": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "date": { "type": [ "string", "null" ] }, "publication_url": { "type": [ "string", "null" ] } }, "required": [ "title", "publication", "description", "date", "publication_url" ] }, "LinkedinUserReaction": { "type": "object", "properties": { "reaction_type": { "type": "string" }, "post": { "allOf": [ { "$ref": "#/components/schemas/LinkedinPost" }, { "type": [ "object", "null" ] } ] } }, "required": [ "reaction_type", "post" ] }, "LinkedinRecommendation": { "type": "object", "properties": { "text": { "type": "string" }, "date": { "type": [ "string", "null" ] }, "relationship": { "type": [ "string", "null" ] }, "recommender": { "type": [ "object", "null" ], "properties": { "urn": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "headline": { "type": "string" }, "avatar_url": { "type": "string" }, "url": { "type": "string" }, "is_premium": { "type": "boolean" } }, "required": [ "urn", "username", "display_name", "headline", "avatar_url", "url", "is_premium" ] } }, "required": [ "text", "date", "relationship", "recommender" ] }, "LinkedinLocation": { "type": "object", "properties": { "country": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] } }, "required": [ "country", "country_code", "city", "postal_code" ], "description": "LinkedIn-shaped location. Any field may be null when the upstream record omits it." }, "LinkedinUser": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "LinkedIn URL slug (public_identifier). Use this as the path parameter for every /linkedin/users/{id}/... endpoint." }, "urn": { "type": "string", "minLength": 1, "description": "LinkedIn internal URN (e.g. `ACoAA...`). Stable across username changes; required by certain LinkedIn-internal flows." }, "username": { "type": "string", "description": "Same value as `id`; included for cross-platform field parity." }, "display_name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "headline": { "type": "string" }, "avatar_url": { "type": "string" }, "cover_image_url": { "type": "string" }, "location": { "$ref": "#/components/schemas/LinkedinLocation" }, "is_premium": { "type": "boolean" }, "is_open_to_work": { "type": "boolean" }, "is_hiring": { "type": "boolean" }, "is_creator": { "type": "boolean" }, "is_influencer": { "type": "boolean" }, "is_top_voice": { "type": "boolean" }, "is_memorialized": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of account creation; null when upstream omits it." }, "website_url": { "type": [ "string", "null" ] }, "associated_hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "urn", "username", "display_name", "first_name", "last_name", "headline", "avatar_url", "cover_image_url", "location", "is_premium", "is_open_to_work", "is_hiring", "is_creator", "is_influencer", "is_top_voice", "is_memorialized", "created_at", "website_url", "associated_hashtags" ], "description": "Canonical LinkedIn user profile. `id` is the URL slug (`public_identifier`); `urn` is the LinkedIn internal opaque id required to call URN-keyed sub-resources upstream — gateway hides that detail behind `/linkedin/users/{id}/*` (see ADR 0006)." }, "LinkedinSkill": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "LinkedinUserVideo": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "duration": { "type": "string" }, "like_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "thumbnail_url": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "url", "duration", "like_count", "comment_count", "thumbnail_url", "created_at" ] }, "LinkedinVolunteer": { "type": "object", "properties": { "title": { "type": "string" }, "cause": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] }, "date": { "$ref": "#/components/schemas/LinkedinDateRange" }, "description": { "type": "string" } }, "required": [ "title", "cause", "organization", "date", "description" ] }, "PiPiXiaHotWord": { "type": "object", "properties": { "word": { "type": "string" }, "rank": { "type": "number" } }, "required": [ "word", "rank" ] }, "PiPiXiaUser": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "user_id": { "type": "string" }, "name": { "type": "string" }, "avatar_url": { "type": "string" }, "description": { "type": "string" }, "follower_count": { "type": "number" }, "following_count": { "type": "number" }, "like_count": { "type": "number" }, "level": { "type": "number" } }, "required": [ "id", "user_id", "name", "avatar_url", "description", "follower_count", "following_count", "like_count", "level" ] }, "PiPiXiaPost": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "PiPiXia cell id (numeric string)." }, "cell_id": { "type": "string" }, "content": { "type": "string" }, "cover_url": { "type": "string" }, "video_url": { "type": "string" }, "create_time": { "type": "number", "description": "Unix-seconds timestamp." }, "digg_count": { "type": "number" }, "comment_count": { "type": "number" }, "share_count": { "type": "number" }, "author_id": { "type": "string" }, "author_name": { "type": "string" } }, "required": [ "id", "cell_id", "content", "cover_url", "video_url", "create_time", "digg_count", "comment_count", "share_count", "author_id", "author_name" ] }, "RedditPost": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Reddit post id (`t3_*` fullname)." }, "title": { "type": "string" }, "url": { "type": "string", "description": "Permalink (or the linked URL for link posts)." }, "text": { "type": "string", "description": "Markdown body for self/text posts; empty otherwise." }, "domain": { "type": "string" }, "created_at": { "type": "string", "description": "Upstream ISO timestamp." }, "is_nsfw": { "type": "boolean" }, "is_spoiler": { "type": "boolean" }, "is_locked": { "type": "boolean" }, "is_stickied": { "type": "boolean" }, "subreddit": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefixed_name": { "type": "string" } }, "required": [ "id", "name", "prefixed_name" ] } }, "required": [ "id", "title", "url", "text", "domain", "created_at", "is_nsfw", "is_spoiler", "is_locked", "is_stickied", "subreddit" ] }, "RedditComment": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Comment id (`t1_*` fullname)." }, "text": { "type": "string" }, "created_at": { "type": "string" }, "score": { "type": "number" }, "author_name": { "type": "string" }, "is_locked": { "type": "boolean" } }, "required": [ "id", "text", "created_at", "score", "author_name", "is_locked" ] }, "RedditSubreddit": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Subreddit slug (URL form without `r/`)." }, "subreddit_t5_id": { "type": "string", "description": "Reddit internal subreddit id (`t5_*` fullname)." }, "name": { "type": "string" }, "prefixed_name": { "type": "string", "description": "Display form like `r/pics`." }, "title": { "type": "string" }, "description": { "type": "string" }, "subscribers_count": { "type": "number" }, "active_count": { "type": "number" }, "is_nsfw": { "type": "boolean" } }, "required": [ "id", "subreddit_t5_id", "name", "prefixed_name", "title", "description", "subscribers_count", "active_count", "is_nsfw" ] }, "RedditTrendingSearch": { "type": "object", "properties": { "query": { "type": "string" } }, "required": [ "query" ] }, "RedditUser": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Reddit username (URL slug)." }, "user_t2_id": { "type": "string", "description": "Reddit internal user id (`t2_*` fullname)." }, "name": { "type": "string" }, "prefixed_name": { "type": "string", "description": "Display form like `u/spez`." }, "karma_total": { "type": "number" }, "karma_from_posts": { "type": "number" }, "karma_from_comments": { "type": "number" }, "is_verified": { "type": "boolean" }, "is_employee": { "type": "boolean" } }, "required": [ "id", "user_t2_id", "name", "prefixed_name", "karma_total", "karma_from_posts", "karma_from_comments", "is_verified", "is_employee" ] }, "ThreadsUser": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Threads URL slug (`username`)." }, "user_id": { "type": "string", "description": "Numeric Threads pk; surfaced for callers that want to skip the gateway-side username → pk stitch." }, "username": { "type": "string" }, "full_name": { "type": "string" }, "biography": { "type": "string" }, "profile_pic_url": { "type": "string" }, "follower_count": { "type": "number" }, "is_verified": { "type": "boolean" }, "is_private": { "type": "boolean" } }, "required": [ "id", "user_id", "username", "full_name", "biography", "profile_pic_url", "follower_count", "is_verified", "is_private" ] }, "ThreadsPost": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Threads post code (URL slug)." }, "code": { "type": "string" }, "media_id": { "type": "string" }, "text": { "type": "string" }, "taken_at": { "type": "number" }, "like_count": { "type": "number" }, "image_url": { "type": "string" }, "video_url": { "type": "string" }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "full_name": { "type": "string" }, "profile_pic_url": { "type": "string" }, "is_verified": { "type": "boolean" } }, "required": [ "id", "username", "full_name", "profile_pic_url", "is_verified" ] } }, "required": [ "id", "code", "media_id", "text", "taken_at", "like_count", "image_url", "video_url", "user" ] }, "Author": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable opaque user id (TikTok sec_uid)" }, "username": { "type": "string", "description": "Public handle, e.g. 'jennmelon'" }, "display_name": { "type": "string" }, "avatar_url": { "type": "string" } }, "required": [ "id", "username", "display_name", "avatar_url" ], "description": "Lightweight author descriptor embedded in Video, Comment, and LiveRoom." }, "Music": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Music id (string form to preserve precision)" }, "title": { "type": "string" }, "author": { "type": "string" }, "is_original": { "type": "boolean" } }, "required": [ "id", "title", "author", "is_original" ], "description": "Music track inlined inside a Video. `null` when the video has no sound track. For the full Music record see `MusicDetail`." }, "Video": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "description": "Per ADR 0004 Rule 6: TikTok title ≡ video_description (Research API states they are the same field)." }, "video_description": { "type": "string" }, "create_time": { "type": "integer", "description": "Unix epoch seconds" }, "duration": { "type": "number", "description": "Seconds" }, "cover_image_url": { "type": "string" }, "share_url": { "type": "string", "description": "Tracking-param-stripped canonical URL" }, "embed_link": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "like_count": { "type": "integer" }, "comment_count": { "type": "integer" }, "share_count": { "type": "integer" }, "view_count": { "type": "integer" }, "author": { "$ref": "#/components/schemas/Author" }, "region": { "type": [ "string", "null" ] }, "hashtags": { "type": "array", "items": { "type": "string" } }, "music": { "$ref": "#/components/schemas/Music" }, "is_image_post": { "type": "boolean" }, "play_url": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "video_description", "create_time", "duration", "cover_image_url", "share_url", "embed_link", "width", "height", "like_count", "comment_count", "share_count", "view_count", "author", "region", "hashtags", "music", "is_image_post", "play_url" ], "description": "A canonical TikTok video. Counts (`like_count`, etc.) are upstream snapshots and not guaranteed monotonic." }, "Hashtag": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "description": "Hashtag name, without the leading #" }, "description": { "type": "string" }, "video_count": { "type": "integer" }, "view_count": { "type": "integer" }, "is_commerce": { "type": "boolean" } }, "required": [ "id", "name", "description", "video_count", "view_count", "is_commerce" ], "description": "A TikTok hashtag (referred to as `challenge` in the upstream)." }, "LiveRoom": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Live room id" }, "title": { "type": "string" }, "cover_image_url": { "type": "string" }, "viewer_count": { "type": "integer" }, "is_online": { "type": "boolean" }, "start_time": { "type": "integer", "description": "Unix epoch seconds" }, "owner": { "$ref": "#/components/schemas/Author" } }, "required": [ "id", "title", "cover_image_url", "viewer_count", "is_online", "start_time", "owner" ], "description": "A canonical TikTok live room." }, "MusicDetail": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "author": { "type": "string" }, "cover_url": { "type": "string" }, "duration": { "type": "number", "description": "Seconds" }, "is_original": { "type": "boolean" }, "play_url": { "type": [ "string", "null" ] }, "user_count": { "type": "integer", "description": "Number of videos that used this music" } }, "required": [ "id", "title", "author", "cover_url", "duration", "is_original", "play_url", "user_count" ], "description": "Full music-track record. The smaller `Music` field on a Video is a subset of this." }, "User": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Stable opaque user id (TikTok sec_uid)" }, "username": { "type": "string" }, "display_name": { "type": "string" }, "avatar_url": { "type": "string" }, "bio": { "type": "string" }, "is_verified": { "type": "boolean" }, "is_private": { "type": "boolean" }, "follower_count": { "type": "integer" }, "following_count": { "type": "integer" }, "like_count": { "type": "integer", "description": "Total likes received across posts" }, "video_count": { "type": "integer" }, "region": { "type": [ "string", "null" ] } }, "required": [ "id", "username", "display_name", "avatar_url", "bio", "is_verified", "is_private", "follower_count", "following_count", "like_count", "video_count", "region" ], "description": "A canonical TikTok user profile. `id` is the platform's stable sec_uid; use it for all user-scoped endpoints." }, "Comment": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "video_id": { "type": "string" }, "text": { "type": "string" }, "create_time": { "type": "integer" }, "like_count": { "type": "integer" }, "reply_count": { "type": "integer" }, "is_author_liked": { "type": "boolean" }, "author": { "$ref": "#/components/schemas/Author" } }, "required": [ "id", "video_id", "text", "create_time", "like_count", "reply_count", "is_author_liked", "author" ], "description": "A top-level comment on a TikTok video. Replies are fetched via /tiktok/videos/{id}/comments/{comment_id}/replies." }, "TwitterUserPreview": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "minLength": 1 }, "rest_id": { "type": "string" }, "screen_name": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "avatar_url": { "type": "string" }, "follower_count": { "type": "number" }, "following_count": { "type": "number" } }, "required": [ "id", "rest_id", "screen_name", "name", "description", "avatar_url", "follower_count", "following_count" ] }, "TwitterMediaItem": { "type": "object", "properties": { "type": { "type": "string" }, "media_url": { "type": "string" }, "video_url": { "type": "string", "description": "MP4 URL for video media; empty otherwise." } }, "required": [ "type", "media_url", "video_url" ] }, "TwitterTweet": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Twitter tweet id (numeric string)." }, "tweet_id": { "type": "string" }, "text": { "type": "string" }, "display_text": { "type": "string" }, "lang": { "type": "string" }, "created_at": { "type": "string", "description": "Upstream's RFC-2822-ish timestamp; passed through." }, "like_count": { "type": "number" }, "retweet_count": { "type": "number" }, "reply_count": { "type": "number" }, "quote_count": { "type": "number" }, "bookmark_count": { "type": "number" }, "view_count": { "type": "number" }, "is_sensitive": { "type": "boolean" }, "conversation_id": { "type": [ "string", "null" ] }, "in_reply_to_tweet_id": { "type": [ "string", "null" ] }, "in_reply_to_screen_name": { "type": [ "string", "null" ] }, "author": { "$ref": "#/components/schemas/TwitterUserPreview" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/TwitterMediaItem" } } }, "required": [ "id", "tweet_id", "text", "display_text", "lang", "created_at", "like_count", "retweet_count", "reply_count", "quote_count", "bookmark_count", "view_count", "is_sensitive", "conversation_id", "in_reply_to_tweet_id", "in_reply_to_screen_name", "author", "media" ] }, "TwitterTrend": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "context": { "type": "string" } }, "required": [ "name", "description", "context" ] }, "TwitterUser": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Twitter URL handle (`screen_name`)." }, "rest_id": { "type": "string", "description": "Numeric Twitter internal id (the `rest_id`)." }, "screen_name": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "avatar_url": { "type": "string" }, "header_image_url": { "type": "string" }, "location": { "type": "string" }, "follower_count": { "type": "number" }, "following_count": { "type": "number" }, "is_verified": { "type": "boolean" }, "is_blue_verified": { "type": "boolean" }, "is_protected": { "type": "boolean" } }, "required": [ "id", "rest_id", "screen_name", "name", "description", "avatar_url", "header_image_url", "location", "follower_count", "following_count", "is_verified", "is_blue_verified", "is_protected" ], "description": "Canonical Twitter / X user. `id` is the URL handle." }, "WeiboHotSearch": { "type": "object", "properties": { "word": { "type": "string" }, "note": { "type": "string" }, "realpos": { "type": "number" }, "label": { "type": "string" } }, "required": [ "word", "note", "realpos", "label" ] }, "WeiboUser": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "minLength": 1, "description": "Weibo numeric uid (string)." }, "uid": { "type": "string" }, "screen_name": { "type": "string" }, "avatar_url": { "type": "string" }, "avatar_hd_url": { "type": "string" }, "cover_url": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "string" }, "gender": { "type": "string" }, "follower_count": { "type": "number" }, "following_count": { "type": "number" }, "statuses_count": { "type": "number" }, "is_verified": { "type": "boolean" }, "verified_reason": { "type": "string" }, "domain": { "type": "string" } }, "required": [ "id", "uid", "screen_name", "avatar_url", "avatar_hd_url", "cover_url", "description", "location", "gender", "follower_count", "following_count", "statuses_count", "is_verified", "verified_reason", "domain" ] }, "WeiboComment": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "text": { "type": "string" }, "created_at": { "type": "string" }, "like_count": { "type": "number" }, "author": { "$ref": "#/components/schemas/WeiboUser" } }, "required": [ "id", "text", "created_at", "like_count", "author" ] }, "WeiboPost": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Weibo numeric post id (string)." }, "mblogid": { "type": "string", "description": "Short URL-friendly mblog id, e.g. `Q4cWS5Bxr`." }, "text": { "type": "string", "description": "Plain text content (text_raw when present, else HTML-stripped fallback)." }, "created_at": { "type": "string", "description": "Upstream's RFC-2822-ish timestamp." }, "source": { "type": "string", "description": "Client/source name (e.g. `iPhone`, `微博视频号`)." }, "repost_count": { "type": "number" }, "comment_count": { "type": "number" }, "like_count": { "type": "number" }, "pic_count": { "type": "number" }, "is_long_text": { "type": "boolean" }, "author": { "$ref": "#/components/schemas/WeiboUser" } }, "required": [ "id", "mblogid", "text", "created_at", "source", "repost_count", "comment_count", "like_count", "pic_count", "is_long_text", "author" ] }, "XiaohongshuNote": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Xiaohongshu note id." }, "note_id": { "type": "string" }, "xsec_token": { "type": "string", "description": "Signed token required by /xiaohongshu/notes/{id} and /comments." }, "type": { "type": "string", "description": "`normal` (image) or `video`." }, "title": { "type": "string" }, "description": { "type": "string" }, "cover_url": { "type": "string" }, "like_count": { "type": "number" }, "comment_count": { "type": "number" }, "collect_count": { "type": "number" }, "share_count": { "type": "number" }, "author": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "nickname": { "type": "string" }, "avatar_url": { "type": "string" } }, "required": [ "id", "nickname", "avatar_url" ] } }, "required": [ "id", "note_id", "xsec_token", "type", "title", "description", "cover_url", "like_count", "comment_count", "collect_count", "share_count", "author" ] }, "XiaohongshuComment": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "create_time": { "type": "number", "description": "Unix-seconds timestamp." }, "like_count": { "type": "number" }, "sub_comment_count": { "type": "number" }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "nickname": { "type": "string" }, "avatar_url": { "type": "string" } }, "required": [ "id", "nickname", "avatar_url" ] } }, "required": [ "id", "content", "create_time", "like_count", "sub_comment_count", "user" ] }, "XiaohongshuUserPreview": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "user_id": { "type": "string" }, "red_id": { "type": "string" }, "nickname": { "type": "string" }, "avatar_url": { "type": "string" }, "sub_title": { "type": "string" }, "note_count": { "type": "number" }, "xsec_token": { "type": "string", "description": "Per-user signed token; pass it along if calling /xiaohongshu/users/{id} via the search-returned id is required." } }, "required": [ "id", "user_id", "red_id", "nickname", "avatar_url", "sub_title", "note_count", "xsec_token" ] }, "XiaohongshuUser": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Xiaohongshu user id (24-character hex)." }, "user_id": { "type": "string" }, "red_id": { "type": "string", "description": "User-visible Red number (e.g. `792402293`)." }, "nickname": { "type": "string" }, "avatar_url": { "type": "string" }, "description": { "type": "string" }, "gender": { "type": "string" }, "ip_location": { "type": "string" }, "follower_count": { "type": "number" }, "following_count": { "type": "number" }, "interaction_count": { "type": "number", "description": "Likes + collects (combined)." } }, "required": [ "id", "user_id", "red_id", "nickname", "avatar_url", "description", "gender", "ip_location", "follower_count", "following_count", "interaction_count" ] }, "YouTubeChannel": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "YouTube channel id (`UCxxx`)." }, "title": { "type": "string" }, "description": { "type": "string" }, "avatar_url": { "type": "string" }, "banner_url": { "type": "string" }, "subscriber_count": { "type": "number", "description": "Best-effort subscriber count from upstream. May be 0 when upstream returns a rounded string only." }, "video_count": { "type": "number" }, "view_count": { "type": "number" }, "country": { "type": "string" }, "is_verified": { "type": "boolean" }, "created_at": { "type": "string", "description": "Upstream creation date string (passed through)." } }, "required": [ "id", "title", "description", "avatar_url", "banner_url", "subscriber_count", "video_count", "view_count", "country", "is_verified", "created_at" ] }, "YouTubeVideoPreview": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "YouTube video id (e.g. `oaSNBz4qMQY`)." }, "title": { "type": "string" }, "author": { "type": "string" }, "channel_id": { "type": "string" }, "description": { "type": "string" }, "duration_seconds": { "type": "number" }, "view_count": { "type": "number" }, "published_time": { "type": "string", "description": "Relative time string from upstream (e.g. `3 weeks ago`)." }, "is_live": { "type": "boolean" }, "category": { "type": "string" } }, "required": [ "id", "title", "author", "channel_id", "description", "duration_seconds", "view_count", "published_time", "is_live", "category" ] }, "YouTubeVideo": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "description": { "type": "string" }, "channel_id": { "type": "string" }, "author": { "type": "string" }, "duration_seconds": { "type": "number" }, "view_count": { "type": "number" }, "keywords": { "type": "array", "items": { "type": "string" } }, "thumbnail_url": { "type": "string" }, "is_live": { "type": "boolean" }, "is_private": { "type": "boolean" } }, "required": [ "id", "title", "description", "channel_id", "author", "duration_seconds", "view_count", "keywords", "thumbnail_url", "is_live", "is_private" ] }, "ZhihuHotItem": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "excerpt": { "type": "string" }, "heat_text": { "type": "string", "description": "Upstream `detail_text`, e.g. `1554 万热度`." }, "answer_count": { "type": "number" }, "follower_count": { "type": "number" } }, "required": [ "id", "title", "url", "excerpt", "heat_text", "answer_count", "follower_count" ] }, "ZhihuUser": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "minLength": 1, "description": "Zhihu URL slug (`url_token`)." }, "url_token": { "type": "string" }, "zhihu_user_id": { "type": "string", "description": "Zhihu internal hex id." }, "name": { "type": "string" }, "headline": { "type": "string" }, "avatar_url": { "type": "string" }, "gender": { "type": "number" }, "is_org": { "type": "boolean" }, "user_type": { "type": "string" } }, "required": [ "id", "url_token", "zhihu_user_id", "name", "headline", "avatar_url", "gender", "is_org", "user_type" ] }, "ZhihuArticle": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "content_html": { "type": "string", "description": "Original HTML content (caller renders)." }, "voteup_count": { "type": "number" }, "comment_count": { "type": "number" }, "created_at": { "type": "number", "description": "Unix-seconds timestamp." }, "updated_at": { "type": "number" }, "image_url": { "type": "string" }, "author": { "$ref": "#/components/schemas/ZhihuUser" } }, "required": [ "id", "title", "excerpt", "content_html", "voteup_count", "comment_count", "created_at", "updated_at", "image_url", "author" ] } }, "parameters": {} }, "paths": { "/bilibili/dynamics/{id}": { "get": { "summary": "Get a Bilibili dynamic by id", "tags": [ "bilibili" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BilibiliDynamic" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bilibili/hot-search": { "get": { "summary": "List Bilibili's current hot search terms", "tags": [ "bilibili" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BilibiliHotSearch" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bilibili/search": { "get": { "summary": "Search Bilibili videos by keyword", "tags": [ "bilibili" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword." }, "required": true, "description": "Search keyword.", "name": "q", "in": "query" }, { "schema": { "type": "string", "description": "Bilibili sort order: `totalrank`, `click`, `pubdate`, `dm`, `stow`." }, "required": false, "description": "Bilibili sort order: `totalrank`, `click`, `pubdate`, `dm`, `stow`.", "name": "order", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BilibiliVideoPreview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bilibili/users/{uid}/dynamic": { "get": { "summary": "List a Bilibili user's dynamic (timeline) entries", "tags": [ "bilibili" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "uid", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BilibiliDynamic" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bilibili/users/{uid}/relation-stat": { "get": { "summary": "Get a Bilibili user's follower/following counts", "tags": [ "bilibili" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "uid", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BilibiliUserRelationStat" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bilibili/users/{uid}/videos": { "get": { "summary": "List videos uploaded by a Bilibili user", "tags": [ "bilibili" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "uid", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BilibiliVideoPreview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/bilibili/videos/{bv_id}": { "get": { "summary": "Get a Bilibili video by BV id", "tags": [ "bilibili" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Bilibili video slug, e.g. `BV1Bo4y1y79G`." }, "required": true, "description": "Bilibili video slug, e.g. `BV1Bo4y1y79G`.", "name": "bv_id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BilibiliVideo" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/explore": { "get": { "summary": "Browse Instagram's Explore feed", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/locations/{id}/nearby": { "get": { "summary": "List Instagram locations geographically near a given location", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/InstagramLocationLite" }, { "type": "object" } ] } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/locations/{id}/posts": { "get": { "summary": "List posts tagged with an Instagram location", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "ranked", "recent" ], "description": "Which tab to fetch — `ranked` (top) or `recent` (latest)." }, "required": false, "description": "Which tab to fetch — `ranked` (top) or `recent` (latest).", "name": "tab", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/locations/{id}": { "get": { "summary": "Get an Instagram location by id", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Numeric Instagram location id." }, "required": true, "description": "Numeric Instagram location id.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstagramLocation" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/posts/{shortcode}/comments/{commentId}/replies": { "get": { "summary": "List replies to an Instagram comment", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "shortcode", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "commentId", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramComment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/posts/{shortcode}/comments": { "get": { "summary": "List comments on an Instagram post", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "shortcode", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "popular", "newest" ], "description": "Comment sort order; defaults to upstream behaviour (popular)." }, "required": false, "description": "Comment sort order; defaults to upstream behaviour (popular).", "name": "sort", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramComment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/posts/{shortcode}": { "get": { "summary": "Get an Instagram post (photo / video / carousel / reel) by shortcode", "description": "`shortcode` is the slug from the post URL, e.g. `DUajw4YkorV` in `instagram.com/p/DUajw4YkorV/`.", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "shortcode", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstagramPost" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/reels/recommended": { "get": { "summary": "Browse Instagram's recommended Reels feed", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/resolve/media-id": { "get": { "summary": "Convert an Instagram post shortcode into its numeric media_id", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "shortcode", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "shortcode": { "type": "string" }, "media_id": { "type": "string" } }, "required": [ "shortcode", "media_id" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/resolve/shortcode-from-media": { "get": { "summary": "Convert an Instagram numeric media_id into its shortcode", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "media_id", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "media_id": { "type": "string" }, "shortcode": { "type": "string" } }, "required": [ "media_id", "shortcode" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/resolve/shortcode": { "get": { "summary": "Extract a post shortcode from an Instagram URL", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uri" }, "required": true, "name": "url", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "shortcode": { "type": "string" } }, "required": [ "url", "shortcode" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/resolve/user-id": { "get": { "summary": "Convert an Instagram username into its numeric user_id (pk)", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "user_id": { "type": "string" } }, "required": [ "username", "user_id" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/search": { "get": { "summary": "Cross-type Instagram search (posts/reels)", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword." }, "required": true, "description": "Search keyword.", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/users/{username}/followers": { "get": { "summary": "List followers of an Instagram user", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/InstagramUserPreview" }, { "type": "object" } ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/users/{username}/following": { "get": { "summary": "List accounts an Instagram user follows", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/InstagramUserPreview" }, { "type": "object" } ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/users/{username}/former-usernames": { "get": { "summary": "List former usernames for an Instagram user", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramFormerUsername" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/users/{username}/highlights": { "get": { "summary": "List Instagram highlight reels for a user (metadata only)", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramHighlight" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/users/{username}/posts": { "get": { "summary": "List feed posts authored by an Instagram user", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/users/{username}/reels": { "get": { "summary": "List reels authored by an Instagram user", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/users/{username}": { "get": { "summary": "Get an Instagram user profile by username", "description": "Returns the canonical Instagram profile for the given URL slug (`username`). Costs 2 upstream calls (gateway resolves `user_id` first).", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Instagram URL slug, e.g. `instagram`" }, "required": true, "description": "Instagram URL slug, e.g. `instagram`", "name": "username", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstagramUser" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/users/{username}/stories": { "get": { "summary": "List active Instagram stories for a user", "description": "Returns the user's currently-live story tray (empty when the user has no active stories).", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/instagram/users/{username}/tagged-posts": { "get": { "summary": "List posts an Instagram user is tagged in", "tags": [ "instagram" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InstagramPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/kuaishou/hot-boards": { "get": { "summary": "List Kuaishou hot-board categories", "tags": [ "kuaishou" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/KuaishouHotBoard" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/kuaishou/hot-search/persons": { "get": { "summary": "List Kuaishou trending personalities", "tags": [ "kuaishou" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/KuaishouHotPerson" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/kuaishou/search": { "get": { "summary": "Search Kuaishou videos by keyword", "tags": [ "kuaishou" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword." }, "required": true, "description": "Search keyword.", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/KuaishouVideo" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/kuaishou/users/{user_id}/hot-posts": { "get": { "summary": "List a Kuaishou user's top-performing videos", "tags": [ "kuaishou" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "user_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/KuaishouVideo" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/kuaishou/users/{user_id}/live-info": { "get": { "summary": "Check whether a Kuaishou user is currently broadcasting", "tags": [ "kuaishou" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "user_id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "is_live": { "type": "boolean" }, "live_stream": { "type": [ "object", "null" ], "additionalProperties": {} } }, "required": [ "is_live", "live_stream" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/kuaishou/users/{user_id}": { "get": { "summary": "Get a Kuaishou user profile", "tags": [ "kuaishou" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "user_id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KuaishouUser" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/kuaishou/videos/{photo_id}/comments": { "get": { "summary": "List comments on a Kuaishou video", "tags": [ "kuaishou" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "photo_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/KuaishouComment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lemon8/hot-search/keywords": { "get": { "summary": "List Lemon8 trending search keywords", "tags": [ "lemon8" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Lemon8HotKeyword" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lemon8/users/{user_id}/followers": { "get": { "summary": "List Lemon8 followers of a user", "tags": [ "lemon8" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "user_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Lemon8User" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lemon8/users/{user_id}/following": { "get": { "summary": "List Lemon8 accounts a user follows", "tags": [ "lemon8" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "user_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Lemon8User" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/lemon8/users/{user_id}": { "get": { "summary": "Get a Lemon8 user profile", "tags": [ "lemon8" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "user_id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lemon8User" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/ads/{id}": { "get": { "summary": "Get a LinkedIn Ad Library entry by ID", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedinAd" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/companies/{slug}/affiliated": { "get": { "summary": "List a LinkedIn company's affiliated pages", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinAffiliatedPage" } } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/companies/{slug}/job-count": { "get": { "summary": "Get the number of active jobs at a LinkedIn company", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedinJobCount" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/companies/{slug}/jobs": { "get": { "summary": "List active job postings at a LinkedIn company", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinJobListing" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/companies/{slug}/member-insights": { "get": { "summary": "Get a LinkedIn company's aggregated member insights", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinMemberInsight" } } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/companies/{slug}/people": { "get": { "summary": "List employees of a LinkedIn company", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinUserPreview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/companies/{slug}/posts": { "get": { "summary": "List posts published by a LinkedIn company page", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/companies/{slug}": { "get": { "summary": "Get a LinkedIn company profile by URL slug", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "LinkedIn URL slug (universal_name), e.g. `microsoft`" }, "required": true, "description": "LinkedIn URL slug (universal_name), e.g. `microsoft`", "name": "slug", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedinCompany" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/groups/{id}/posts": { "get": { "summary": "List posts in a LinkedIn group", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/groups/{id}": { "get": { "summary": "Get a LinkedIn group by ID", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedinGroup" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/jobs/{id}": { "get": { "summary": "Get a LinkedIn job posting by ID", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "If true, upstream includes the inferred required-skills list (counts as 1 additional upstream call)." }, "required": false, "description": "If true, upstream includes the inferred required-skills list (counts as 1 additional upstream call).", "name": "include_skills", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedinJob" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/posts/{id}/comments/{comment_id}/replies": { "get": { "summary": "List replies to a LinkedIn comment", "description": "`cursor` here is LinkedIn's `previous_replies_token`. On the first page, send no cursor — LinkedIn's upstream still expects the param, so the gateway passes `-` as the sentinel it documents.", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "comment_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinComment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/posts/{id}/comments": { "get": { "summary": "List top-level comments on a LinkedIn post", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinComment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/posts/{id}/reactions": { "get": { "summary": "List users who reacted to a LinkedIn post", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "all", "like", "praise", "empathy", "interest", "appreciation", "entertainment" ], "default": "all", "description": "Filter by reaction type. `all` returns every reaction (default)." }, "required": false, "description": "Filter by reaction type. `all` returns every reaction (default).", "name": "type", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinUserPreview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/posts/{id}/reposts": { "get": { "summary": "List reposts of a LinkedIn post", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/posts/{id}": { "get": { "summary": "Get a LinkedIn post by ID", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedinPost" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/search/ads": { "get": { "summary": "Search the LinkedIn Ad Library", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "keyword", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "advertiser_name", "in": "query" }, { "schema": { "type": "string", "description": "ISO-3166-1 alpha-2 code, e.g. `US`" }, "required": false, "description": "ISO-3166-1 alpha-2 code, e.g. `US`", "name": "country", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "date", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinAdListing" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/search/industries": { "get": { "summary": "Resolve a free-text industry name to LinkedIn industry IDs", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "keyword", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinSearchIndustry" } } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/search/jobs": { "get": { "summary": "Search LinkedIn jobs by keyword and filters", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Free-text search query" }, "required": true, "description": "Free-text search query", "name": "keyword", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "sort_by", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "date_posted", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "geocode", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "company", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "experience_level", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "remote", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "job_type", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "easy_apply", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "has_verifications", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "under_10_applicants", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "name": "fair_chance_employer", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinJobListing" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/search/locations": { "get": { "summary": "Resolve a free-text location into LinkedIn geocode tokens", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "keyword", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinSearchLocation" } } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/search/people": { "get": { "summary": "Search LinkedIn people by name, title, company, etc.", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "name", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "first_name", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "last_name", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "title", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "company", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "school", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "geocode_location", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "current_company", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "profile_language", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "industry", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "service_category", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinUserPreview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/search/posts": { "get": { "summary": "Search LinkedIn posts by keyword", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "keyword", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "date_posted", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "sort_by", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "from_member", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "from_company", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "content_type", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinSearchPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/search/schools": { "get": { "summary": "Search LinkedIn schools by keyword", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "keyword", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinSchool" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/about": { "get": { "summary": "Get a LinkedIn profile's 'about' metadata", "description": "Returns the timeline metadata block (joined date, contact freshness, profile photo freshness). Costs 2 upstream calls (ADR 0006).", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedinAbout" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/certifications": { "get": { "summary": "List a LinkedIn user's certifications", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinCertification" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/comments": { "get": { "summary": "List comments authored by a LinkedIn user", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinUserComment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/contact": { "get": { "summary": "Get a LinkedIn user's public contact info", "description": "Returns the contact block (websites, phone numbers, twitter handles, address, wechat) the user has chosen to publish on LinkedIn.", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedinContactInfo" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/educations": { "get": { "summary": "List a LinkedIn user's education", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinEducation" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/experience": { "get": { "summary": "List a LinkedIn user's work experience", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinExperience" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/follower-count": { "get": { "summary": "Get a LinkedIn user's follower & connection counts", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedinFollowerStats" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/honors": { "get": { "summary": "List a LinkedIn user's honors and awards", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinHonor" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/images": { "get": { "summary": "List image posts authored by a LinkedIn user", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinUserImage" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/interests/companies": { "get": { "summary": "List companies a LinkedIn user follows", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinInterestCompany" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/interests/groups": { "get": { "summary": "List LinkedIn groups a user follows", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinInterestGroup" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/posts": { "get": { "summary": "List posts authored by a LinkedIn user", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/publications": { "get": { "summary": "List a LinkedIn user's publications", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinPublication" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/reactions": { "get": { "summary": "List reactions a LinkedIn user has placed on posts", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinUserReaction" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/recommendations": { "get": { "summary": "List recommendations written for a LinkedIn user", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinRecommendation" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}": { "get": { "summary": "Get a LinkedIn user profile by URL slug", "description": "Returns the canonical LinkedIn profile for the given URL slug (`public_identifier`). Returns 404 not_found if no such user exists.", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "LinkedIn URL slug, e.g. `williamhgates`" }, "required": true, "description": "LinkedIn URL slug, e.g. `williamhgates`", "name": "username", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedinUser" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/skills": { "get": { "summary": "List a LinkedIn user's skills", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinSkill" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/videos": { "get": { "summary": "List video posts authored by a LinkedIn user", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinUserVideo" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/linkedin/users/{username}/volunteers": { "get": { "summary": "List a LinkedIn user's volunteer experience", "tags": [ "linkedin" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedinVolunteer" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/pipixia/hot-search/words": { "get": { "summary": "List PiPiXia trending search words", "tags": [ "pipixia" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PiPiXiaHotWord" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/pipixia/users/{user_id}/followers": { "get": { "summary": "List PiPiXia followers of a user", "tags": [ "pipixia" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "user_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PiPiXiaUser" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/pipixia/users/{user_id}/following": { "get": { "summary": "List PiPiXia accounts a user follows", "tags": [ "pipixia" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "user_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PiPiXiaUser" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/pipixia/users/{user_id}/posts": { "get": { "summary": "List PiPiXia posts by user", "tags": [ "pipixia" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "user_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PiPiXiaPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/pipixia/users/{user_id}": { "get": { "summary": "Get a PiPiXia user profile", "tags": [ "pipixia" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "user_id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PiPiXiaUser" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reddit/feed/home": { "get": { "summary": "Browse Reddit's anonymous home feed", "tags": [ "reddit" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RedditPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reddit/feed/news": { "get": { "summary": "Browse Reddit's news feed", "tags": [ "reddit" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RedditPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reddit/feed/popular": { "get": { "summary": "Browse Reddit's popular feed", "tags": [ "reddit" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RedditPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reddit/posts/{id}/comments": { "get": { "summary": "List Reddit comments on a post", "tags": [ "reddit" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RedditComment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reddit/posts/{id}": { "get": { "summary": "Get a Reddit post by id", "tags": [ "reddit" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Reddit post fullname, e.g. `t3_1thjm1o`." }, "required": true, "description": "Reddit post fullname, e.g. `t3_1thjm1o`.", "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditPost" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reddit/subreddits/{name}": { "get": { "summary": "Get a Reddit subreddit by name", "tags": [ "reddit" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Subreddit slug without `r/`, e.g. `pics`." }, "required": true, "description": "Subreddit slug without `r/`, e.g. `pics`.", "name": "name", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditSubreddit" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reddit/trending-searches": { "get": { "summary": "List Reddit's current trending search queries", "tags": [ "reddit" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RedditTrendingSearch" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reddit/users/{username}/comments": { "get": { "summary": "List Reddit comments authored by a user", "tags": [ "reddit" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RedditComment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reddit/users/{username}/posts": { "get": { "summary": "List Reddit posts authored by a user", "tags": [ "reddit" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RedditPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/reddit/users/{username}": { "get": { "summary": "Get a Reddit user profile by username", "tags": [ "reddit" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditUser" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/search/profiles": { "get": { "summary": "Search Threads users by keyword", "tags": [ "threads" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Search keyword." }, "required": true, "description": "Search keyword.", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadsUser" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/search/recent": { "get": { "summary": "Search recent Threads posts", "tags": [ "threads" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword." }, "required": true, "description": "Search keyword.", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadsPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/search/top": { "get": { "summary": "Search top Threads posts", "tags": [ "threads" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword." }, "required": true, "description": "Search keyword.", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadsPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/users/{username}/posts": { "get": { "summary": "List Threads posts authored by a user", "tags": [ "threads" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadsPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/users/{username}/replies": { "get": { "summary": "List Threads replies authored by a user", "tags": [ "threads" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadsPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/users/{username}/reposts": { "get": { "summary": "List Threads reposts by a user", "tags": [ "threads" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadsPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/threads/users/{username}": { "get": { "summary": "Get a Threads user profile by username", "tags": [ "threads" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "username", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadsUser" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/feed/recommended": { "post": { "summary": "Get TikTok home-feed recommendation videos", "description": "Returns recommendation videos from TikTok's home feed. Optionally pass the caller's TikTok cookie in the request body for personalized recs; without it the response is a generic recommendation set.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cookie": { "type": "string", "description": "Optional TikTok cookie for personalized recommendations. Forwarded as-is." } }, "default": {} } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/hashtags/{id}": { "get": { "summary": "Get a TikTok hashtag by ID", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hashtag" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/hashtags/{id}/videos": { "get": { "summary": "List videos tagged with a TikTok hashtag", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/lives/{room_id}": { "get": { "summary": "Get a TikTok live room by ID", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$" }, "required": true, "name": "room_id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveRoom" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/lives/{room_id}/status": { "get": { "summary": "Check whether a TikTok live room is online", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$" }, "required": true, "name": "room_id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "room_id": { "type": "string" }, "is_online": { "type": "boolean" } }, "required": [ "room_id", "is_online" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/lives/trending": { "get": { "summary": "List today's trending TikTok live rooms (ranking)", "description": "Returns the daily-rank trending TikTok live rooms. Each entry is a thin ranking row (rank + score + room_id + minimal creator info). Call /tiktok/lives/{room_id} to fetch the full live-room object.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "score": { "type": "integer" }, "room_id": { "type": "string", "minLength": 1 }, "owner_username": { "type": "string" }, "owner_display_name": { "type": "string" }, "owner_avatar_url": { "type": "string" } }, "required": [ "rank", "score", "room_id", "owner_username", "owner_display_name", "owner_avatar_url" ] } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/music/{id}": { "get": { "summary": "Get a TikTok music track by ID", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MusicDetail" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/music/{id}/videos": { "get": { "summary": "List videos using a TikTok music track", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/music/charts": { "get": { "summary": "List TikTok trending music charts", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1, "default": 0, "description": "0 = Top 50 (default), 1 = Viral 50" }, "required": false, "description": "0 = Top 50 (default), 1 = Viral 50", "name": "scene", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MusicDetail" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/search/hashtags": { "get": { "summary": "Search TikTok hashtags by keyword", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword" }, "required": true, "description": "Search keyword", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Hashtag" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/search/lives": { "get": { "summary": "Search TikTok live rooms by keyword", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword" }, "required": true, "description": "Search keyword", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LiveRoom" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/search/music": { "get": { "summary": "Search TikTok music by keyword", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword" }, "required": true, "description": "Search keyword", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MusicDetail" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/search": { "get": { "summary": "General TikTok search (returns videos)", "description": "Returns videos matching the keyword `q` from TikTok's mixed-type general search. Non-video result types are filtered out — call the type-specific endpoints (/tiktok/search/users, /tiktok/search/hashtags, /tiktok/search/music, /tiktok/search/lives) when needed.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword" }, "required": true, "description": "Search keyword", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/search/users": { "get": { "summary": "Search TikTok users by keyword", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword" }, "required": true, "description": "Search keyword", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/search/videos": { "get": { "summary": "Search TikTok videos by keyword", "description": "Returns a paginated list of TikTok videos matching the keyword `q`. Use `next_cursor` from the response as the next request's `cursor`. When `has_more` is false, `next_cursor` is null.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword" }, "required": true, "description": "Search keyword", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/users/{id}/followers": { "get": { "summary": "List a TikTok user's followers", "description": "Returns a paginated list of users following the given user.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 20, "description": "TikTok sec_uid" }, "required": true, "description": "TikTok sec_uid", "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/users/{id}/following": { "get": { "summary": "List users a TikTok user is following", "description": "Returns a paginated list of users the given user is following.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 20, "description": "TikTok sec_uid" }, "required": true, "description": "TikTok sec_uid", "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/users/{id}/likes": { "get": { "summary": "List videos liked by a TikTok user", "description": "Returns a paginated list of videos the user has liked (where the user has made their likes public). Empty when likes are hidden.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 20, "description": "TikTok sec_uid" }, "required": true, "description": "TikTok sec_uid", "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/users/{id}": { "get": { "summary": "Get a TikTok user profile by sec_uid", "description": "Returns the canonicalized public profile for the TikTok user with the given sec_uid. Returns 404 not_found if the user does not exist or is private.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 20, "description": "TikTok sec_uid" }, "required": true, "description": "TikTok sec_uid", "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/users/{id}/similar": { "get": { "summary": "List TikTok users similar to the given user", "description": "Returns a paginated list of users TikTok recommends as similar to the given user. The `limit` parameter is best-effort — upstream may ignore it.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 20, "description": "TikTok sec_uid" }, "required": true, "description": "TikTok sec_uid", "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/users/{id}/videos": { "get": { "summary": "List videos posted by a TikTok user", "description": "Returns a paginated list of public videos posted by the user with the given sec_uid. Use `next_cursor` from the response as the next request's `cursor`. When `has_more` is false, `next_cursor` is null.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 20, "description": "TikTok sec_uid" }, "required": true, "description": "TikTok sec_uid", "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/users/resolve": { "get": { "summary": "Resolve a TikTok username to a user id", "description": "Accepts a public TikTok username (handle) and returns the user's stable opaque id (sec_uid) that other /tiktok/users/{id} endpoints accept. Returns 404 not_found if no user with that username exists.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Public TikTok handle, e.g. 'jennmelon'" }, "required": true, "description": "Public TikTok handle, e.g. 'jennmelon'", "name": "username", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable opaque sec_uid" }, "username": { "type": "string" } }, "required": [ "id", "username" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/videos/{id}/comments/{comment_id}/replies": { "get": { "summary": "List replies to a TikTok comment", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "pattern": "^\\d+$" }, "required": true, "name": "comment_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/videos/{id}/comments": { "get": { "summary": "List top-level comments on a TikTok video", "description": "Returns a paginated list of top-level comments on the given video. Use `next_cursor` from the response as the next request's `cursor`. When `has_more` is false, `next_cursor` is null.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/videos/{id}": { "get": { "summary": "Get a TikTok video by ID", "description": "Returns canonicalized metadata for a single TikTok video. The `{id}` must be the numeric TikTok video id (aweme_id). Returns 404 not_found if the video is missing, deleted, or private. Returns 400 invalid_id if the upstream rejects the id format.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^\\d+$", "description": "Numeric TikTok video id (aweme_id)" }, "required": true, "description": "Numeric TikTok video id (aweme_id)", "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/videos/batch": { "post": { "summary": "Batch-fetch TikTok videos by ID", "description": "Returns canonicalized metadata for up to 50 videos in a single call. Request body is a JSON array of numeric TikTok video IDs.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 50, "description": "Up to 50 numeric TikTok video ids" } }, "required": [ "ids" ], "description": "JSON body with an `ids` array" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiktok/videos/resolve": { "get": { "summary": "Resolve a TikTok share URL to a video", "description": "Accepts a TikTok share URL (long or short / vm.tiktok.com) and returns the canonical Video object. The host must be one of: www.tiktok.com, tiktok.com, m.tiktok.com, vm.tiktok.com, vt.tiktok.com. Returns 404 not_found if the URL is invalid or the video is missing/deleted/private.", "tags": [ "tiktok" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uri", "description": "TikTok share URL (long or short form)" }, "required": true, "description": "TikTok share URL (long or short form)", "name": "url", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/twitter/search": { "get": { "summary": "Search Twitter / X tweets by keyword", "tags": [ "twitter" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword." }, "required": true, "description": "Search keyword.", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TwitterTweet" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/twitter/trending": { "get": { "summary": "List current Twitter / X trends", "tags": [ "twitter" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TwitterTrend" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/twitter/tweets/{id}/comments": { "get": { "summary": "List replies to a Twitter / X tweet", "tags": [ "twitter" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TwitterTweet" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/twitter/tweets/{id}": { "get": { "summary": "Get a Twitter / X tweet by id", "tags": [ "twitter" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Tweet id (numeric string)." }, "required": true, "description": "Tweet id (numeric string).", "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwitterTweet" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/twitter/users/{screen_name}/followers": { "get": { "summary": "List followers of a Twitter / X user", "tags": [ "twitter" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "screen_name", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/TwitterUserPreview" }, { "type": "object" } ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/twitter/users/{screen_name}/following": { "get": { "summary": "List accounts a Twitter / X user follows", "tags": [ "twitter" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "screen_name", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/TwitterUserPreview" }, { "type": "object" } ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/twitter/users/{screen_name}/media": { "get": { "summary": "List tweets with media authored by a user", "tags": [ "twitter" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "screen_name", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TwitterTweet" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/twitter/users/{screen_name}": { "get": { "summary": "Get a Twitter / X user profile by screen_name", "tags": [ "twitter" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Twitter URL handle without the leading `@`, e.g. `elonmusk`." }, "required": true, "description": "Twitter URL handle without the leading `@`, e.g. `elonmusk`.", "name": "screen_name", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwitterUser" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/twitter/users/{screen_name}/tweet-replies": { "get": { "summary": "List tweets and replies authored by a user", "tags": [ "twitter" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "screen_name", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TwitterTweet" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/twitter/users/{screen_name}/tweets": { "get": { "summary": "List tweets authored by a Twitter / X user", "tags": [ "twitter" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "screen_name", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TwitterTweet" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/weibo/hot-search": { "get": { "summary": "List Weibo realtime trending topics", "tags": [ "weibo" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WeiboHotSearch" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/weibo/posts/{id}/comments": { "get": { "summary": "List comments on a Weibo post", "tags": [ "weibo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WeiboComment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/weibo/posts/{id}": { "get": { "summary": "Get a Weibo post by id", "tags": [ "weibo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Numeric Weibo post id (mid)." }, "required": true, "description": "Numeric Weibo post id (mid).", "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WeiboPost" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/weibo/users/{uid}/fans": { "get": { "summary": "List Weibo followers of a user", "tags": [ "weibo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "uid", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/WeiboUser" }, { "type": "object" } ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/weibo/users/{uid}/following": { "get": { "summary": "List accounts a Weibo user follows", "tags": [ "weibo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "uid", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/WeiboUser" }, { "type": "object" } ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/weibo/users/{uid}/posts": { "get": { "summary": "List Weibo posts by a user", "tags": [ "weibo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "uid", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WeiboPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/weibo/users/{uid}": { "get": { "summary": "Get a Weibo user profile by uid", "tags": [ "weibo" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "uid", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WeiboUser" }, { "type": "object" } ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/xiaohongshu/homefeed": { "get": { "summary": "Browse Xiaohongshu's anonymous home feed", "tags": [ "xiaohongshu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/XiaohongshuNote" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/xiaohongshu/notes/{id}/comments": { "get": { "summary": "List comments on a Xiaohongshu note (requires xsec_token)", "tags": [ "xiaohongshu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Per-note signed token." }, "required": true, "description": "Per-note signed token.", "name": "xsec_token", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/XiaohongshuComment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/xiaohongshu/notes/{id}": { "get": { "summary": "Get a Xiaohongshu note by id (requires xsec_token)", "tags": [ "xiaohongshu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "minLength": 1, "description": "Per-note signed token returned by upstream alongside `note_id`." }, "required": true, "description": "Per-note signed token returned by upstream alongside `note_id`.", "name": "xsec_token", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XiaohongshuNote" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/xiaohongshu/search/notes": { "get": { "summary": "Search Xiaohongshu notes by keyword", "tags": [ "xiaohongshu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword." }, "required": true, "description": "Search keyword.", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/XiaohongshuNote" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/xiaohongshu/search/users": { "get": { "summary": "Search Xiaohongshu users by keyword", "tags": [ "xiaohongshu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword." }, "required": true, "description": "Search keyword.", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/XiaohongshuUserPreview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/xiaohongshu/users/{id}/notes": { "get": { "summary": "List Xiaohongshu notes by user", "tags": [ "xiaohongshu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/XiaohongshuNote" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/xiaohongshu/users/{id}": { "get": { "summary": "Get a Xiaohongshu user profile", "tags": [ "xiaohongshu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Xiaohongshu user id (24-character hex)." }, "required": true, "description": "Xiaohongshu user id (24-character hex).", "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XiaohongshuUser" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/youtube/channels/{channel_id}": { "get": { "summary": "Get a YouTube channel by id", "tags": [ "youtube" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "YouTube channel id (`UCxxx...`)." }, "required": true, "description": "YouTube channel id (`UCxxx...`).", "name": "channel_id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YouTubeChannel" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/youtube/channels/{channel_id}/shorts": { "get": { "summary": "List Shorts uploaded by a YouTube channel", "tags": [ "youtube" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channel_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/YouTubeVideoPreview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/youtube/channels/{channel_id}/videos": { "get": { "summary": "List videos uploaded by a YouTube channel", "tags": [ "youtube" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "channel_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/YouTubeVideoPreview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/youtube/resolve/channel-id": { "get": { "summary": "Resolve a YouTube channel URL to its UC… channel id", "tags": [ "youtube" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uri", "description": "Full channel URL — supports `youtube.com/@handle`, `/channel/UC…`, `/c/name`." }, "required": true, "description": "Full channel URL — supports `youtube.com/@handle`, `/channel/UC…`, `/c/name`.", "name": "url", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "channel_id": { "type": "string" } }, "required": [ "url", "channel_id" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/youtube/search": { "get": { "summary": "Search YouTube videos by keyword", "tags": [ "youtube" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Search keyword." }, "required": true, "description": "Search keyword.", "name": "q", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/YouTubeVideoPreview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/youtube/trending": { "get": { "summary": "Browse YouTube's trending videos", "tags": [ "youtube" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Optional language code, e.g. `en`." }, "required": false, "description": "Optional language code, e.g. `en`.", "name": "language_code", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/YouTubeVideoPreview" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/youtube/videos/{video_id}/related": { "get": { "summary": "List YouTube videos related to a given video", "tags": [ "youtube" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "video_id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/YouTubeVideoPreview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/youtube/videos/{video_id}": { "get": { "summary": "Get a YouTube video by id", "tags": [ "youtube" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "YouTube video id, e.g. `oaSNBz4qMQY`." }, "required": true, "description": "YouTube video id, e.g. `oaSNBz4qMQY`.", "name": "video_id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YouTubeVideo" } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/zhihu/hot-list": { "get": { "summary": "List Zhihu's current trending questions", "tags": [ "zhihu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 }, "required": false, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ZhihuHotItem" } } }, "required": [ "items" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/zhihu/questions/{id}/answers": { "get": { "summary": "List answers to a Zhihu question", "tags": [ "zhihu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ZhihuArticle" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/zhihu/users/{url_token}/articles": { "get": { "summary": "List Zhihu articles by user", "tags": [ "zhihu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "url_token", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ZhihuArticle" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/zhihu/users/{url_token}/followees": { "get": { "summary": "List accounts a Zhihu user follows", "tags": [ "zhihu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "url_token", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ZhihuUser" }, { "type": "object" } ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/zhihu/users/{url_token}/followers": { "get": { "summary": "List Zhihu followers of a user", "tags": [ "zhihu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "url_token", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ZhihuUser" }, { "type": "object" } ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "items", "has_more", "next_cursor" ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/zhihu/users/{url_token}": { "get": { "summary": "Get a Zhihu user profile by url_token", "tags": [ "zhihu" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Zhihu URL slug, e.g. `excited-vczh`." }, "required": true, "description": "Zhihu URL slug, e.g. `excited-vczh`.", "name": "url_token", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ZhihuUser" }, { "type": "object" } ] } } } }, "400": { "description": "Validation or invalid-id error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid upstream credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Upstream error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": {} }