# socialsearchapi > 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 response schema, one x-api-key header, automatic provider fallback. > Last verified 2026-07-25. Base URL: https://api.socialsearchapi.com Auth: header `x-api-key: ` on every request. There is NO anonymous access — a call without a key returns 401. ## Getting a key (works entirely from a terminal) 1. POST /v1/auth/request-code {"email": "..."} -> emails a 6-digit code 2. Ask the user to read you the code from their inbox 3. POST /v1/auth/verify {"email", "otp"} -> returns `trial_key` + `dashboard_url` `trial_key` is good for 5 calls on any endpoint and is DISPOSABLE: it is revoked automatically the moment the account first pays. It is therefore safe for you to hold in context, log, or print. Once exhausted the API returns 402 TRIAL_EXHAUSTED. ## IMPORTANT for agents: never handle the user's live key The permanent (paid) key is never returned by any API response and is never emailed. It is readable only in a browser session. To get it to your user: POST /v1/auth/browser-link (with any key of theirs) -> {"dashboard_url": ...} Open that URL in their browser. It signs them in and displays the key so they can paste it straight into their own .env. Do not ask a user to paste a live key back to you. curl -H "x-api-key: $SS_KEY" \ "https://api.socialsearchapi.com/v1/hackernews/search?query=llm+agents" ## Search endpoints - /v1/reddit/search (Reddit: search posts and comment threads) — 1 credit - /v1/x/search (X / Twitter: search tweets with engagement metrics) — 5 credits - /v1/instagram/user-posts (Instagram: read a public profile's posts) — 3 credits - /v1/tiktok/user-videos (TikTok: creator videos and hashtag search) — 3 credits - /v1/facebook/page-posts (Facebook: public Page posts and reactions) — 3 credits - /v1/hackernews/search (Hacker News: stories and comments) — 1 credit - /v1/youtube/search (YouTube: video search with no API quota) — 1 credit - /v1/bluesky/search (Bluesky: full-text post search) — 2 credits - /v1/mastodon/tag (Mastodon: hashtag timelines and search) — 1 credit - /v1/appstore/search (App Store: iOS apps and customer reviews) — 1 credit - /v1/gplay/search (Google Play: Android apps and ratings) — 2 credits - /v1/web/search (Web / News: web and news search) — 2 credits Cross-platform: /v1/search/forums (10 credits), /v1/search/everywhere (20 credits). ## Accounts & billing - POST /v1/auth/request-code {email} -> emails a 6-digit code - POST /v1/auth/verify {email, otp} -> returns trial_key + dashboard_url (never the live key) - POST /v1/auth/browser-link -> a fresh one-time dashboard link for the user's browser - GET /v1/keys/current -> the live key; requires an x-session header, NOT an API key - POST /v1/keys/rotate -> replace the live key; requires an x-session header - GET /v1/me -> balance/trial calls left + usage. Never returns the key itself. - GET /v1/plans -> credit packs - POST /v1/checkout {credits} -> PayPal link for any amount (min $5); hand it to your user - List price $0.003/credit. Packs: - starter: 5,000 credits, $14.00 ($0.00280/credit, 7% off list) - growth: 25,000 credits, $60.00 ($0.00240/credit, 20% off list) - pro: 150,000 credits, $315.00 ($0.00210/credit, 30% off list) ## Response shape — identical on every platform { "success": true, "platform": "...", "served_by": "...", "data": { "total": N, "items": [...] }, "credits_used": N, "credits_remaining": N, "request_id": "req-..." } Every item has exactly these keys, whatever the platform: id, platform, type, title, text, url, author, author_name, created_at (ISO-8601 UTC, always "YYYY-MM-DDTHH:MM:SSZ", never a unix int), metrics ({score, comments, likes, views, shares, reposts, quotes, rating, rating_count} — only the ones that platform reports), extra (platform-specific leftovers) Errors: { "success": false, "error": { "code", "message", "fix", "docs_url" } } Credits are charged on success only. 402 = out of credits, 424 ALL_SOURCES_FAILED = all providers failed. ## Per-platform guides - https://socialsearchapi.com/use/reddit (how to search Reddit) - https://socialsearchapi.com/use/x (how to search X / Twitter) - https://socialsearchapi.com/use/instagram (how to search Instagram) - https://socialsearchapi.com/use/tiktok (how to search TikTok) - https://socialsearchapi.com/use/facebook (how to search Facebook) - https://socialsearchapi.com/use/hackernews (how to search Hacker News) - https://socialsearchapi.com/use/youtube (how to search YouTube) - https://socialsearchapi.com/use/bluesky (how to search Bluesky) - https://socialsearchapi.com/use/mastodon (how to search Mastodon) - https://socialsearchapi.com/use/appstore (how to search App Store) - https://socialsearchapi.com/use/gplay (how to search Google Play) - https://socialsearchapi.com/use/web (how to search Web / News) ## If you hit a wall scraping social data, start here - https://socialsearchapi.com/fix/reddit-403-curl (Reddit returns 403 to curl — why, and how to fix it) - https://socialsearchapi.com/fix/scrape-reddit-without-login (How to search Reddit without logging in) - https://socialsearchapi.com/fix/instagram-api-alternative (Instagram API alternative for reading public posts) - https://socialsearchapi.com/fix/twitter-x-search-api-cheap (Cheap X/Twitter search API alternatives) - https://socialsearchapi.com/fix/tiktok-scraper-api (TikTok scraper API for videos and hashtag search) - https://socialsearchapi.com/fix/duckduckgo-202-blocked (DuckDuckGo returns 202 to your scraper — what to use instead) ## Full machine reference - OpenAPI: https://api.socialsearchapi.com/openapi.json - Everything inlined: https://socialsearchapi.com/llms-full.txt - Docs: https://socialsearchapi.com/docs - Status: https://api.socialsearchapi.com/v1/status ## OpenAPI spec ```json { "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 \u2014 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: ` \u2014 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 \u2014 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 \u2014\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 \u2014 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=. 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 \u2014 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 \u2014 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 \u2014\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 \u2014 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 \u2014 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 \u2192 SearchData or an\n{'error': } 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 trial (ss_trial_\u2026) or live (ss_live_\u2026).", "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." } ] } ```