{"openapi":"3.1.0","info":{"title":"socialsearchapi","description":"One API across every social platform. Search and read Reddit, X/Twitter, Instagram, TikTok, Facebook, Hacker News, YouTube, Bluesky, Mastodon, and the app stores — unified schema, one `x-api-key` header, automatic provider fallback. Built for developers and the agents working beside them.\n\nAuth: every call needs `x-api-key: <your key>` — there is no anonymous tier. Get a free 5-call trial key: POST /v1/auth/request-code {email}, read the code from your inbox, then POST /v1/auth/verify {email, otp}.","contact":{"name":"socialsearchapi","url":"https://socialsearchapi.com/"},"license":{"name":"Terms","url":"https://socialsearchapi.com/terms"},"version":"1.0.0"},"servers":[{"url":"https://api.socialsearchapi.com","description":"production"},{"url":"http://localhost:8940","description":"local"}],"paths":{"/v1/hackernews/search":{"get":{"tags":["Hacker News"],"summary":"Search stories and comments","description":"Full-text search over Hacker News via the official Algolia index.","operationId":"hn_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"tags","in":"query","required":false,"schema":{"type":"string","maxLength":60,"default":"story","title":"Tags"}},{"name":"hitsPerPage","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":30,"title":"Hitsperpage"}},{"name":"sort","in":"query","required":false,"schema":{"enum":["relevance","date"],"type":"string","default":"relevance","title":"Sort"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/github/search":{"get":{"tags":["GitHub"],"summary":"Search repositories, code and issues","description":"GitHub search across repositories, code, issues or users.","operationId":"gh_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Per Page"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","maxLength":20,"default":"","title":"Sort"}},{"name":"kind","in":"query","required":false,"schema":{"enum":["repositories","code","issues","users"],"type":"string","default":"repositories","title":"Kind"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/google_news/search":{"get":{"tags":["Web & News"],"summary":"Search news","description":"Recent news results for a query.","operationId":"news_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":30,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/youtube/search":{"get":{"tags":["YouTube"],"summary":"Search videos","description":"Video search with channel, duration and view count. No Google API quota is consumed.","operationId":"yt_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/reddit/search":{"get":{"tags":["Reddit"],"summary":"Search Reddit posts","description":"Full-text search across Reddit. Primary path is a native old.reddit scrape over a residential proxy; if it is blocked or empty we fail over to a backup provider automatically and `served_by` names whichever one answered.","operationId":"reddit_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"sort","in":"query","required":false,"schema":{"enum":["relevance","hot","top","new","comments"],"type":"string","default":"relevance","title":"Sort"}},{"name":"t","in":"query","required":false,"schema":{"enum":["all","hour","day","week","month","year"],"type":"string","default":"all","title":"T"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/reddit/subreddit/search":{"get":{"tags":["Reddit"],"summary":"Search inside one subreddit","description":"Same as Reddit search, scoped to a single subreddit.","operationId":"reddit_sub_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"subreddit","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"Subreddit"}},{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"sort","in":"query","required":false,"schema":{"enum":["relevance","hot","top","new","comments"],"type":"string","default":"relevance","title":"Sort"}},{"name":"t","in":"query","required":false,"schema":{"enum":["all","hour","day","week","month","year"],"type":"string","default":"all","title":"T"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/reddit/omni-search":{"get":{"tags":["Reddit"],"summary":"Search threads and their comments","description":"Returns matching threads plus their top comments in one call, so an agent gets the discussion rather than just the titles.","operationId":"reddit_omni","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"threads","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":8,"title":"Threads"}},{"name":"comments","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":0,"default":8,"title":"Comments"}},{"name":"sort","in":"query","required":false,"schema":{"enum":["relevance","hot","top","new","comments"],"type":"string","default":"relevance","title":"Sort"}},{"name":"t","in":"query","required":false,"schema":{"enum":["all","hour","day","week","month","year"],"type":"string","default":"all","title":"T"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/web/search":{"get":{"tags":["Web & News"],"summary":"Search the web","description":"General web search returning title, url and snippet.","operationId":"web_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/appstore/search":{"get":{"tags":["App Store"],"summary":"Search iOS apps","description":"App search through the official iTunes endpoint, with rating and price.","operationId":"appstore_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","default":"us","title":"Country"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/appstore/reviews":{"get":{"tags":["App Store"],"summary":"Read customer reviews","description":"Customer reviews for one iOS app, by country.","operationId":"appstore_reviews","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"app_id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"App Id"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","default":"us","title":"Country"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"default":1,"title":"Page"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/gplay/search":{"get":{"tags":["Google Play"],"summary":"Search Android apps","description":"Google Play app search with rating and install band.","operationId":"gplay_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":30,"minimum":1,"default":10,"title":"Limit"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","default":"us","title":"Country"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/gplay/details":{"get":{"tags":["Google Play"],"summary":"Read a Play listing","description":"Full listing detail for one Android app id.","operationId":"gplay_details","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"app_id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"App Id"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","default":"us","title":"Country"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileEnvelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/bluesky/search-actors":{"get":{"tags":["Bluesky"],"summary":"Search accounts","description":"Find Bluesky accounts by name or handle.","operationId":"bsky_actors","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":15,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/bluesky/author-feed":{"get":{"tags":["Bluesky"],"summary":"Read an account's feed","description":"Recent posts from one Bluesky handle.","operationId":"bsky_feed","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"actor","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"Actor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/bluesky/search":{"get":{"tags":["Bluesky"],"summary":"Full-text search posts","description":"Search Bluesky posts over the AT Protocol, with like, reply and repost counts.","operationId":"bsky_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/mastodon/tag":{"get":{"tags":["Mastodon"],"summary":"Read a hashtag timeline","description":"Public timeline for one hashtag. `instance` must be a public Mastodon hostname (validated before any request is made).","operationId":"masto_tag","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"tag","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"Tag"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"default":25,"title":"Limit"}},{"name":"instance","in":"query","required":false,"schema":{"type":"string","maxLength":253,"default":"mastodon.social","title":"Instance"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/mastodon/search":{"get":{"tags":["Mastodon"],"summary":"Search posts","description":"Search public Mastodon posts.","operationId":"masto_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/x/search":{"get":{"tags":["X / Twitter"],"summary":"Search tweets","description":"Full-text tweet search with engagement metrics and author follower counts.","operationId":"x_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"query_type","in":"query","required":false,"schema":{"enum":["Latest","Top"],"type":"string","default":"Latest","title":"Query Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/x/user-tweets":{"get":{"tags":["X / Twitter"],"summary":"Read an account's recent tweets","description":"Latest tweets for one handle, newest first.","operationId":"x_user_tweets","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"username","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"Username"}},{"name":"include_replies","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Replies"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/instagram/user-posts":{"get":{"tags":["Instagram"],"summary":"Read a public profile's posts","description":"Recent posts for a public Instagram handle, with caption, likes, comments and view counts.","operationId":"ig_posts","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"Handle"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/instagram/profile":{"get":{"tags":["Instagram"],"summary":"Read a public profile","description":"Profile metadata for a public Instagram handle.","operationId":"ig_profile","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"Handle"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileEnvelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/instagram/search-profiles":{"get":{"tags":["Instagram"],"summary":"Search Instagram profiles","description":"Find public profiles by name or keyword. Instagram removed public hashtag search, so profile lookup is the supported entry point.","operationId":"ig_search","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/tiktok/user-videos":{"get":{"tags":["TikTok"],"summary":"Read a creator's videos","description":"Recent videos for a TikTok handle, with play, like, comment and share counts.","operationId":"tt_videos","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"Handle"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/tiktok/hashtag":{"get":{"tags":["TikTok"],"summary":"Search TikTok by hashtag","description":"Videos carrying a given hashtag.","operationId":"tt_hashtag","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"hashtag","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"Hashtag"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/tiktok/profile":{"get":{"tags":["TikTok"],"summary":"Read a TikTok profile","description":"Profile metadata for a TikTok handle.","operationId":"tt_profile","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"handle","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"Handle"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileEnvelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/facebook/page-posts":{"get":{"tags":["Facebook"],"summary":"Read a public Page's posts","description":"Recent posts from a public Facebook Page URL, with reaction and comment counts.","operationId":"fb_posts","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","minLength":4,"maxLength":500,"title":"Url"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/facebook/profile":{"get":{"tags":["Facebook"],"summary":"Read a public Page","description":"Page metadata for a public Facebook URL.","operationId":"fb_profile","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","minLength":4,"maxLength":500,"title":"Url"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileEnvelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/search/forums":{"get":{"tags":["Cross-platform"],"summary":"Search Reddit and Hacker News together","description":"One query, both forums, merged into a single ranked list in the shared item schema. Pricing is honest about partial results: if a source fails you are charged pro-rata for the sources that answered (the `sources` block in the response shows exactly which), and a response where every source failed costs nothing.","operationId":"forums","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}},{"name":"threads","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":6,"title":"Threads"}},{"name":"comments","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":0,"default":6,"title":"Comments"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompositeEnvelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/search/everywhere":{"get":{"tags":["Cross-platform"],"summary":"Search every platform at once","description":"Fans the query out across every live platform and merges the results. Costs more because it is many upstream calls in one request — and only for what serves: partial responses are charged pro-rata for the sources that answered (`sources` in the response), and a total failure costs nothing.","operationId":"everywhere","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":400,"title":"Query"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompositeEnvelope"}}}},"401":{"description":"Missing or unknown x-api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"INSUFFICIENT_CREDITS or TRIAL_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"A parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"424":{"description":"Upstream provider failure (never charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/credits/balance":{"get":{"tags":["Account"],"summary":"Your credit balance","description":"Just the balance, for a cheap pre-flight check.","operationId":"balance","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"ApiKeyHeader":[]}]}},"/v1/status":{"get":{"tags":["Status"],"summary":"Service and provider health","description":"Liveness plus which upstream providers are configured. Unauthenticated.","operationId":"status","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/auth/request-code":{"post":{"tags":["Account"],"summary":"Email a 6-digit sign-in code","description":"Step 1 of sign-in. Same call whether the address is new or returning —\nthere is no separate signup. Works from a web form or from a terminal, so an\nagent can drive it while the user reads the code out of their own inbox.","operationId":"request_code","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/verify":{"post":{"tags":["Account"],"summary":"Verify the code — returns a trial key and a browser link","description":"Step 2. Returns a disposable trial key (safe for an agent to hold) and a\nsingle-use `dashboard_url`. The live key is never in this response.","operationId":"verify_code","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/session":{"post":{"tags":["Account"],"summary":"Exchange a one-time browser link for a session","description":"Called by the dashboard when it loads with ?s=<magic>. Burns the single-use token and returns a session token.","operationId":"open_session","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/browser-link":{"post":{"tags":["Account"],"summary":"Mint a fresh one-time dashboard link","description":"Authenticated with any of the caller's own API keys. Lets an agent open an authenticated dashboard tab for its user without ever handling the live key itself.","operationId":"browser_link","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"ApiKeyHeader":[]}]}},"/v1/keys/current":{"get":{"tags":["Account"],"summary":"Read the live key (browser session only, shown once)","description":"Requires an x-session header from /v1/auth/session. Deliberately NOT reachable with an API key, so a terminal agent cannot read it. Keys are hashed at rest: the plaintext is returned exactly once — on the first visit after paying, or right after a rotate.","operationId":"keys_current","parameters":[{"name":"x-session","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Session"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keys/rotate":{"post":{"tags":["Account"],"summary":"Rotate the live key (browser session only)","operationId":"keys_rotate","parameters":[{"name":"x-session","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Session"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/me":{"get":{"tags":["Account"],"summary":"Your balance and usage","description":"Balance and usage for the calling key — or for the signed-in browser session (x-session). Never returns the key itself.","operationId":"me","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"x-session","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Session"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/plans":{"get":{"tags":["Billing"],"summary":"Credit packs and rates","description":"Available credit packs, the exact per-credit rate of each, and the discount against list.","operationId":"plans","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/checkout":{"post":{"tags":["Billing"],"summary":"Create a PayPal order for credits","description":"Works with any of the caller's API keys, or with a browser session —\nlive keys are show-once, so the dashboard pays via its session.","operationId":"checkout","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"x-session","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Session"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/checkout/confirm":{"post":{"tags":["Billing"],"summary":"Capture a PayPal order and add credits","description":"Called by the /pay/success page when the buyer returns from PayPal. Safe to repeat: fulfillment is exactly-once. The webhook and a server-side reconciliation loop are the backups, so credits arrive even if the browser never comes back.","operationId":"checkout_confirm","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/paypal/webhook":{"post":{"tags":["Internal"],"summary":"PayPal webhook receiver","operationId":"paypal_webhook","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/admin/overview":{"get":{"tags":["Internal"],"summary":"Owner operations overview","operationId":"admin_overview","security":[{"ApiKeyHeader":[]}],"parameters":[{"name":"hours","in":"query","required":false,"schema":{"type":"integer","default":24,"title":"Hours"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/admin/providers":{"get":{"tags":["Internal"],"summary":"Owner provider balances","description":"Live balances of paid upstreams — so we see credits running out before users do.","operationId":"admin_providers","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"ApiKeyHeader":[]}]}}},"components":{"schemas":{"CheckoutIn":{"properties":{"credits":{"anyOf":[{"type":"integer","maximum":10000000.0,"minimum":1.0},{"type":"null"}],"title":"Credits"},"plan":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Plan"}},"type":"object","title":"CheckoutIn"},"CompositeEnvelope":{"properties":{"success":{"type":"boolean","title":"Success"},"platform":{"type":"string","title":"Platform"},"endpoint":{"type":"string","title":"Endpoint"},"data":{"additionalProperties":true,"type":"object","title":"Data"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Remaining","description":"null for the unmetered owner key."},"request_id":{"type":"string","title":"Request Id","description":"Quote this in support requests — it is stored with the call record."},"served_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Served By","description":"Which provider answered, when relevant."},"trial":{"anyOf":[{"$ref":"#/components/schemas/TrialBlock"},{"type":"null"}]},"sources":{"anyOf":[{"$ref":"#/components/schemas/SourcesBlock"},{"type":"null"}]},"partial":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Partial","description":"true when at least one source failed."}},"type":"object","required":["success","platform","endpoint","data","credits_used","request_id"],"title":"CompositeEnvelope","description":"Cross-platform endpoints: `data` maps source name → SearchData or an\n{'error': <state>} block. Pricing pro-rates on sources served."},"ConfirmIn":{"properties":{"order_id":{"type":"string","maxLength":64,"title":"Order Id"}},"type":"object","required":["order_id"],"title":"ConfirmIn"},"Envelope":{"properties":{"success":{"type":"boolean","title":"Success"},"platform":{"type":"string","title":"Platform"},"endpoint":{"type":"string","title":"Endpoint"},"data":{"$ref":"#/components/schemas/SearchData"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Remaining","description":"null for the unmetered owner key."},"request_id":{"type":"string","title":"Request Id","description":"Quote this in support requests — it is stored with the call record."},"served_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Served By","description":"Which provider answered, when relevant."},"trial":{"anyOf":[{"$ref":"#/components/schemas/TrialBlock"},{"type":"null"}]}},"type":"object","required":["success","platform","endpoint","data","credits_used","request_id"],"title":"Envelope","description":"Every successful response, on every platform."},"ErrorEnvelope":{"properties":{"success":{"type":"boolean","title":"Success","default":false},"endpoint":{"type":"string","title":"Endpoint"},"error":{"$ref":"#/components/schemas/ErrorInfo"},"credits_used":{"type":"integer","title":"Credits Used","default":0},"request_id":{"type":"string","title":"Request Id"}},"type":"object","required":["endpoint","error","request_id"],"title":"ErrorEnvelope"},"ErrorInfo":{"properties":{"type":{"type":"string","title":"Type","description":"Stable machine-readable code, e.g. INSUFFICIENT_CREDITS, TRIAL_EXHAUSTED, RATE_LIMITED."},"message":{"type":"string","title":"Message"},"status":{"type":"integer","title":"Status"},"docs_url":{"type":"string","title":"Docs Url"},"fix":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fix","description":"What to do next — meant for agents."}},"type":"object","required":["type","message","status","docs_url"],"title":"ErrorInfo"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Item":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"platform":{"type":"string","title":"Platform"},"type":{"type":"string","title":"Type"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author"},"author_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author Name"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At","description":"Always ISO-8601 UTC (YYYY-MM-DDTHH:MM:SSZ), never a unix int."},"metrics":{"$ref":"#/components/schemas/Metrics"},"extra":{"additionalProperties":true,"type":"object","title":"Extra","description":"Platform-specific leftovers, incl. created_at_raw."}},"type":"object","required":["platform","type","metrics"],"title":"Item","description":"The unified item — identical keys on every platform (schema.py enforces\nit centrally, so a new connector is unified by default)."},"Metrics":{"properties":{"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"},"comments":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Comments"},"likes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Likes"},"views":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Views"},"shares":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Shares"},"reposts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reposts"},"quotes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Quotes"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"rating_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rating Count"}},"additionalProperties":true,"type":"object","title":"Metrics","description":"Engagement counts. Only the keys the platform actually provides are\npresent — a Reddit post has score+comments, a TikTok video views+likes."},"ProfileEnvelope":{"properties":{"success":{"type":"boolean","title":"Success"},"platform":{"type":"string","title":"Platform"},"endpoint":{"type":"string","title":"Endpoint"},"data":{"additionalProperties":true,"type":"object","title":"Data"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Remaining","description":"null for the unmetered owner key."},"request_id":{"type":"string","title":"Request Id","description":"Quote this in support requests — it is stored with the call record."},"served_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Served By","description":"Which provider answered, when relevant."},"trial":{"anyOf":[{"$ref":"#/components/schemas/TrialBlock"},{"type":"null"}]}},"type":"object","required":["success","platform","endpoint","data","credits_used","request_id"],"title":"ProfileEnvelope","description":"Profile/detail endpoints: `data` is a single object, not an item list."},"SearchData":{"properties":{"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"},"items":{"items":{"$ref":"#/components/schemas/Item"},"type":"array","title":"Items","default":[]}},"additionalProperties":true,"type":"object","title":"SearchData"},"SessionIn":{"properties":{"magic":{"type":"string","title":"Magic"}},"type":"object","required":["magic"],"title":"SessionIn"},"SignupIn":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"agent":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Agent"}},"type":"object","required":["email"],"title":"SignupIn"},"SourcesBlock":{"properties":{"ok":{"type":"integer","title":"Ok"},"failed":{"type":"integer","title":"Failed"},"by_source":{"additionalProperties":{"type":"string"},"type":"object","title":"By Source","description":"Per-source state: ok | not_configured | timeout | rate_limited | blocked | upstream_error."}},"type":"object","required":["ok","failed","by_source"],"title":"SourcesBlock"},"TrialBlock":{"properties":{"calls_remaining":{"type":"integer","title":"Calls Remaining"},"of":{"type":"integer","title":"Of"},"note":{"type":"string","title":"Note"},"upgrade":{"type":"string","title":"Upgrade"}},"type":"object","required":["calls_remaining","of","note","upgrade"],"title":"TrialBlock"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VerifyIn":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"otp":{"type":"string","maxLength":12,"title":"Otp"}},"type":"object","required":["email","otp"],"title":"VerifyIn"}},"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","description":"Your API key — trial (ss_trial_…) or live (ss_live_…).","in":"header","name":"x-api-key"}}},"tags":[{"name":"search","description":"Search & read social platforms (unified schema)."},{"name":"accounts","description":"Signup (shared agent+human, email OTP), keys, balance."},{"name":"billing","description":"PayPal credit-pack + custom-amount checkout."},{"name":"admin","description":"Owner-only observability: failures, payments, margin."},{"name":"meta","description":"Status & credit balance."}]}