{"openapi":"3.1.0","info":{"title":"supercenter.dev API","version":"1.0.0","description":"Synchronous atomic capabilities for web, social, advertising, and commerce data."},"servers":[{"url":"https://supercenter.dev"}],"paths":{"/v1/web/search":{"post":{"operationId":"web_search","summary":"Search the web","description":"Search the public web and get clean, relevant excerpts from top results.\n\nBest for: Current information, latest news, announcements, facts, funding, broad research, and public pages such as LinkedIn posts.\nReturns: Result titles, source URLs, relevant excerpts, publication dates, and normalized relevance scores when available.\nQuery tips: Describe the ideal page in a specific natural-language sentence, not only keywords. For public LinkedIn posts, include the topic, place, and date range.\nNext: Use people_search or companies_search for structured records. Use web_read when an excerpt is not sufficient.","tags":["Web"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":512,"description":"Natural-language description of the ideal page. Use a specific sentence, not only keywords. For public LinkedIn posts, include the topic, place, and date range."},"limit":{"default":10,"description":"Maximum number of results to return (1-25, default 10).","type":"integer","minimum":1,"maximum":25}},"required":["query"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"snippet":{"type":"string","description":"Short relevant excerpt from the page."},"publishedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"score":{"type":"number","minimum":0,"maximum":1}},"required":["url","title","snippet"]}}},"required":["results"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/web/read":{"post":{"operationId":"web_read","summary":"Read pages","description":"Read known public webpages as clean full text.\n\nBest for: Extracting or summarizing complete content after web_search, or reading exact URLs supplied by the user.\nReturns: Clean page content with the source URL, page title, and per-URL fetch status.\nQuery tips: Batch up to 10 URLs in one call instead of reading each page separately.","tags":["Web"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","format":"uri"},"description":"Public http(s) URLs to fetch and convert to clean text (1-10)."}},"required":["urls"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"title":{"type":"string"},"content":{"type":"string"},"failed":{"default":false,"type":"boolean"}},"required":["url","content"]}}},"required":["pages"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/people/search":{"post":{"operationId":"people_search","summary":"Search people","description":"Search public professional and LinkedIn profiles.\n\nBest for: Finding employees, founders, executives, and public professional profiles by employer, role, or location.\nReturns: Name, current title, company, location, profile URL, and a relevant excerpt when available.\nQuery tips: Describe the person or experience required. Put exact employer, role, and location constraints in their separate fields.\nNext: Use social_profile on a selected profile URL for full public details. Use social_posts for recent activity.","tags":["Discovery"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":512,"description":"Natural-language description of the desired person, such as 'revenue leader with enterprise SaaS experience'. Put exact employer, role, and location constraints in their separate fields."},"limit":{"default":10,"description":"Maximum records to return (1-25, default 10).","type":"integer","minimum":1,"maximum":25},"location":{"description":"Current location filter. Use a city, region, or country, such as 'Vienna' or 'Austria'.","type":"string","minLength":1,"maxLength":120},"role":{"description":"Current role or job-title filter, such as 'Head of Operations' or 'Founder'.","type":"string","minLength":1,"maxLength":160},"company":{"description":"Current employer filter, such as 'Consigma'. Use this field when an exact company is known.","type":"string","minLength":1,"maxLength":200}},"required":["query"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"people":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"profile_url":{"type":"string","format":"uri"},"avatar_url":{"type":"string","format":"uri"},"headline":{"type":"string"},"company":{"type":"string"},"location":{"type":"string"},"snippet":{"type":"string"}},"required":["name","profile_url"]}}},"required":["people"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/companies/search":{"post":{"operationId":"companies_search","summary":"Search companies","description":"Search and return structured public company records.\n\nBest for: Company discovery, account research, market maps, and comparisons by industry or location.\nReturns: Company name, website, public profile URL, description, industry, and location when available.\nQuery tips: Describe the ideal company. Put exact industry and location constraints in their separate fields.\nNext: Use web_search for broader follow-up coverage, then web_read for complete source pages.","tags":["Discovery"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":512,"description":"Natural-language description of the desired company, such as 'B2B software companies serving mid-market retailers'. Put exact industry and location constraints in their separate fields."},"limit":{"default":10,"description":"Maximum records to return (1-25, default 10).","type":"integer","minimum":1,"maximum":25},"location":{"description":"Current location filter. Use a city, region, or country, such as 'Vienna' or 'Austria'.","type":"string","minLength":1,"maxLength":120},"industry":{"description":"Industry or market filter, such as 'logistics software' or 'industrial automation'.","type":"string","minLength":1,"maxLength":160}},"required":["query"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"companies":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"website":{"type":"string","format":"uri"},"profile_url":{"type":"string","format":"uri"},"description":{"type":"string"},"industry":{"type":"string"},"location":{"type":"string"}},"required":["name"]}}},"required":["companies"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/find/contact_detail":{"post":{"operationId":"find_contact_detail","summary":"Find contact details","description":"Find a person's verified work email or phone number from their name and company domain.\n\nBest for: Outreach preparation after the person and company are already known.\nReturns: The found email address with its verification status, or the found phone number, or both. Missing details come back as null.\nQuery tips: Request only the types you need: lookups charge 5 credits per email and 30 credits per phone from the workspace balance. Include linkedin_url whenever it is known; it strongly improves phone results.\nNext: Use people_search first when the person or their LinkedIn URL is not known yet.","tags":["Discovery"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"types":{"minItems":1,"maxItems":2,"type":"array","items":{"type":"string","enum":["email","phone"]},"description":"Contact detail types to look up: ['email'], ['phone'], or ['email', 'phone']. Each requested type is priced separately, so request only the types you need."},"full_name":{"type":"string","minLength":1,"maxLength":200,"description":"The person's full name, such as 'Jane Smith'."},"company_domain":{"type":"string","minLength":1,"maxLength":200,"description":"The current employer's website domain, such as 'example.com'. Pass a bare domain, not a URL."},"linkedin_url":{"description":"The person's LinkedIn profile URL, such as 'https://www.linkedin.com/in/janesmith'. Optional, but it strongly improves phone match rates and enables backup lookup routes.","type":"string","format":"uri"}},"required":["types","full_name","company_domain"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"email":{"anyOf":[{"type":"object","properties":{"address":{"type":"string","minLength":1},"status":{"type":"string"}},"required":["address"]},{"type":"null"}]},"phone":{"anyOf":[{"type":"object","properties":{"number":{"type":"string","minLength":1}},"required":["number"]},{"type":"null"}]}},"required":["email","phone"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/social/profile":{"post":{"operationId":"social_profile","summary":"Get social profile","description":"Retrieve one exact public social profile from its URL.\n\nBest for: Inspecting a known LinkedIn, Instagram, TikTok, X, YouTube, or Facebook person, company, page, or channel.\nReturns: Available bio, audience metrics, work history, education, links, account details, recent posts, and the normalized public source record.\nQuery tips: Pass a profile or channel URL, not a post URL. The network is detected from the URL.\nNext: Use social_posts when more recent posts or pagination are required.","tags":["Social"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public LinkedIn, Instagram, TikTok, X, YouTube, or Facebook profile URL over HTTPS. Use a profile or channel URL, not a post URL."}},"required":["url"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"network":{"type":"string","enum":["linkedin","instagram","tiktok","x","youtube","facebook"]},"url":{"type":"string","format":"uri"},"source_url":{"type":"string","format":"uri"},"profile_id":{"type":"string"},"handle":{"type":"string"},"display_name":{"type":"string"},"headline":{"type":"string"},"bio":{"type":"string"},"location":{"type":"string"},"avatar_url":{"type":"string","format":"uri"},"followers":{"type":"integer","minimum":0,"maximum":9007199254740991},"following":{"type":"integer","minimum":0,"maximum":9007199254740991},"posts":{"type":"integer","minimum":0,"maximum":9007199254740991},"connections":{"type":"integer","minimum":0,"maximum":9007199254740991},"total_likes":{"type":"integer","minimum":0,"maximum":9007199254740991},"total_views":{"type":"integer","minimum":0,"maximum":9007199254740991},"verified":{"type":"boolean"},"private":{"type":"boolean"},"business":{"type":"boolean"},"category":{"type":"string"},"website_url":{"type":"string","format":"uri"},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"label":{"type":"string","minLength":1}},"required":["url"]}},"categories":{"type":"array","items":{"type":"string","minLength":1}},"experience":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","minLength":1},"organization":{"type":"string","minLength":1},"organization_url":{"type":"string","format":"uri"},"location":{"type":"string","minLength":1},"employment_type":{"type":"string","minLength":1},"workplace_type":{"type":"string","minLength":1},"start_date":{"type":"string","minLength":1},"end_date":{"type":"string","minLength":1},"duration":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"skills":{"default":[],"type":"array","items":{"type":"string","minLength":1}}},"required":["title"]}},"education":{"type":"array","items":{"type":"object","properties":{"institution":{"type":"string","minLength":1},"institution_url":{"type":"string","format":"uri"},"degree":{"type":"string","minLength":1},"field_of_study":{"type":"string","minLength":1},"start_date":{"type":"string","minLength":1},"end_date":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"skills":{"default":[],"type":"array","items":{"type":"string","minLength":1}}},"required":["institution"]}},"skills":{"type":"array","items":{"type":"string","minLength":1}},"languages":{"type":"array","items":{"type":"string","minLength":1}},"certifications":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"issuer":{"type":"string","minLength":1},"issued_at":{"type":"string","minLength":1},"expires_at":{"type":"string","minLength":1},"credential_url":{"type":"string","format":"uri"}},"required":["name"]}},"account_details":{"type":"object","properties":{"has_channel":{"type":"boolean"},"highlight_reel_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"joined_recently":{"type":"boolean"},"has_public_story":{"type":"boolean"},"restricted":{"type":"boolean"},"restriction_reason":{"type":"string"},"facebook_page":{"type":"string"},"facebook_id":{"type":"string"},"video_count":{"type":"integer","minimum":0,"maximum":9007199254740991}}},"recent_posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"},"source_url":{"type":"string","format":"uri"},"text":{"default":"","type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"author_handle":{"type":"string"},"author_name":{"type":"string"},"media_urls":{"default":[],"type":"array","items":{"type":"string","format":"uri"}},"likes":{"type":"integer","minimum":0,"maximum":9007199254740991},"comments":{"type":"integer","minimum":0,"maximum":9007199254740991},"shares":{"type":"integer","minimum":0,"maximum":9007199254740991},"views":{"type":"integer","minimum":0,"maximum":9007199254740991},"source_data":{"description":"Complete public source record returned for this post.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","url"]}},"related_profiles":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"source_url":{"type":"string","format":"uri"},"handle":{"type":"string"},"display_name":{"type":"string"},"bio":{"type":"string"},"avatar_url":{"type":"string","format":"uri"},"followers":{"type":"integer","minimum":0,"maximum":9007199254740991},"verified":{"type":"boolean"},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["url"]}},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Complete public source record returned for this profile. Internal execution metadata is excluded."}},"required":["network","url","source_data"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/social/posts":{"post":{"operationId":"social_posts","summary":"List social posts","description":"List recent public posts or videos from one social profile URL.\n\nBest for: Reviewing recent activity from a known LinkedIn, Instagram, TikTok, X, YouTube, or Facebook profile or channel.\nReturns: Available post text, dates, author details, media, engagement metrics, source records, and an opaque next-page cursor.\nQuery tips: Pass the profile or channel URL. Use the returned cursor with the same URL and limit for the next page.\nNext: Use social_post on a selected post URL for its complete normalized record and available metrics.","tags":["Social"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public LinkedIn, Instagram, TikTok, X, YouTube, or Facebook profile URL over HTTPS. Use a profile or channel URL, not a post URL."},"limit":{"default":10,"description":"Maximum recent public posts or videos to return (1-50, default 10).","type":"integer","minimum":1,"maximum":50},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."}},"required":["url"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"network":{"type":"string","enum":["linkedin","instagram","tiktok","x","youtube","facebook"]},"profile_url":{"type":"string","format":"uri"},"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"},"source_url":{"type":"string","format":"uri"},"text":{"default":"","type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"author_handle":{"type":"string"},"author_name":{"type":"string"},"media_urls":{"default":[],"type":"array","items":{"type":"string","format":"uri"}},"likes":{"type":"integer","minimum":0,"maximum":9007199254740991},"comments":{"type":"integer","minimum":0,"maximum":9007199254740991},"shares":{"type":"integer","minimum":0,"maximum":9007199254740991},"views":{"type":"integer","minimum":0,"maximum":9007199254740991},"source_data":{"description":"Complete public source record returned for this post.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","url"]}},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."},"has_more":{"default":false,"type":"boolean"}},"required":["network","profile_url","posts"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/social/post":{"post":{"operationId":"social_post","summary":"Get social post","description":"Retrieve one exact public social post or video from its URL.\n\nBest for: Reading complete text and available engagement data for a known LinkedIn, Instagram, TikTok, X, YouTube, or Facebook post.\nReturns: Available full text, date, author, media, reactions, comments, views, and the normalized public source record.\nQuery tips: Pass the exact public post, video, or reel URL. The network is detected from the URL.\nNext: Use social_comments for comment text and replies. Use social_reactions for reactor identities when the network supports them. Use social_transcript when the post contains spoken video.","tags":["Social"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public LinkedIn, Instagram, TikTok, X, YouTube, or Facebook post, video, or reel URL over HTTPS."}},"required":["url"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"network":{"type":"string","enum":["linkedin","instagram","tiktok","x","youtube","facebook"]},"post":{"type":"object","properties":{"id":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"},"source_url":{"type":"string","format":"uri"},"text":{"default":"","type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"author_handle":{"type":"string"},"author_name":{"type":"string"},"media_urls":{"default":[],"type":"array","items":{"type":"string","format":"uri"}},"likes":{"type":"integer","minimum":0,"maximum":9007199254740991},"comments":{"type":"integer","minimum":0,"maximum":9007199254740991},"shares":{"type":"integer","minimum":0,"maximum":9007199254740991},"views":{"type":"integer","minimum":0,"maximum":9007199254740991},"source_data":{"description":"Complete public source record returned for this post.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","url"]}},"required":["network","post"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/social/comments":{"post":{"operationId":"social_comments","summary":"List social comments","description":"List public comments and optional replies for one exact social post URL.\n\nBest for: Reading audience discussion, reactions, questions, and reply threads on a known social post or video.\nReturns: Commenter identity, text, date, reactions, reply counts, nesting, source records, and an opaque next-page cursor when available.\nQuery tips: Enable include_replies only when reply text is needed. Reuse the cursor with the same URL and filters for the next page.","tags":["Social"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public LinkedIn, Instagram, TikTok, X, YouTube, or Facebook post, video, or reel URL over HTTPS."},"limit":{"default":50,"description":"Maximum public comments to return (1-100, default 50).","type":"integer","minimum":1,"maximum":100},"include_replies":{"default":false,"description":"Include public replies when the source supports them (default false).","type":"boolean"},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."}},"required":["url"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"network":{"type":"string","enum":["linkedin","instagram","tiktok","x","youtube","facebook"]},"post_url":{"type":"string","format":"uri"},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"},"source_url":{"type":"string","format":"uri"},"text":{"default":"","type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"author_name":{"type":"string"},"author_handle":{"type":"string"},"author_profile_url":{"type":"string","format":"uri"},"author_avatar_url":{"type":"string","format":"uri"},"likes":{"type":"integer","minimum":0,"maximum":9007199254740991},"replies":{"type":"integer","minimum":0,"maximum":9007199254740991},"parent_id":{"type":"string"},"depth":{"type":"integer","minimum":0,"maximum":9007199254740991},"pinned":{"type":"boolean"},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Complete public source record returned for this comment."}},"required":["id","source_data"]}},"has_more":{"default":false,"type":"boolean"},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."}},"required":["network","post_url","comments"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/social/reactions":{"post":{"operationId":"social_reactions","summary":"List social post reactions","description":"List the public people or organizations that reacted to one social post or comment.\n\nBest for: Audience research, engagement analysis, and finding public profiles that reacted to known social content.\nReturns: Normalized reaction type, reactor name, public profile URL, position, avatar, complete public source record, and a signal when the requested limit may have truncated the list.\nQuery tips: Pass one exact public social post or comment URL. LinkedIn is supported in V1. Use reaction_types only when specific reactions are required. Increase limit up to 100 when has_more is true.\nNext: Use social_profile on a selected reactor profile URL for complete public profile details.","tags":["Social"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public social post or comment URL over HTTPS. LinkedIn is supported in V1."},"limit":{"default":50,"description":"Maximum public reactions to return (1-100, default 50).","type":"integer","minimum":1,"maximum":100},"reaction_types":{"description":"Optional normalized reaction types to include. Omit this field to include all types.","minItems":1,"maxItems":6,"type":"array","items":{"type":"string","enum":["like","celebrate","support","love","insightful","funny"],"description":"Normalized public reaction type."}}},"required":["url"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"network":{"type":"string","enum":["linkedin","instagram","tiktok","x","youtube","facebook"]},"post_url":{"type":"string","format":"uri"},"reactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"reaction_type":{"type":"string","enum":["like","celebrate","support","love","insightful","funny"],"description":"Normalized public reaction type."},"reactor_name":{"type":"string"},"reactor_profile_url":{"type":"string","format":"uri"},"reactor_position":{"type":"string"},"reactor_avatar_url":{"type":"string","format":"uri"},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Complete public source record returned for this reaction."}},"required":["id","reaction_type","source_data"]}},"has_more":{"default":false,"type":"boolean"}},"required":["network","post_url","reactions"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/social/search":{"post":{"operationId":"social_search","summary":"Search social","description":"Find and search one social network for public profiles, accounts, posts, or videos.\n\nBest for: Discovering LinkedIn, Instagram, TikTok, X, YouTube, or Facebook content when no exact URL is known.\nReturns: Normalized profile or post results with source URLs, public text, identity, media, and available metrics.\nQuery tips: Describe the topic, person, company, or account in natural language. For LinkedIn posts, include the topic, place, and date range.\nNext: Use social_profile, social_posts, or social_post on selected URLs for exact records. LinkedIn search results do not include verified engagement metrics.","tags":["Social"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"network":{"type":"string","enum":["linkedin","instagram","tiktok","x","youtube","facebook"],"description":"Social network to search."},"result_type":{"type":"string","enum":["profiles","posts"],"description":"Type of public social result to return."},"query":{"type":"string","minLength":1,"maxLength":160,"description":"Natural-language description of the profile or post to find. For LinkedIn posts, include the topic, place, and date range."},"limit":{"type":"integer","minimum":1,"maximum":25,"description":"Maximum results to return (1-25)."},"cursor":{"description":"Opaque cursor from the previous response. Reuse it only with the same network, result type, and query.","type":"string","minLength":1,"maxLength":4096}},"required":["network","result_type","query","limit"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"network":{"type":"string","enum":["linkedin","instagram","tiktok","x","youtube","facebook"]},"result_type":{"type":"string","enum":["profiles","posts"]},"results":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"url":{"type":"string","format":"uri"},"source_url":{"type":"string","format":"uri"},"text":{"default":"","type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"author_handle":{"type":"string"},"author_name":{"type":"string"},"media_urls":{"default":[],"type":"array","items":{"type":"string","format":"uri"}},"likes":{"type":"integer","minimum":0,"maximum":9007199254740991},"comments":{"type":"integer","minimum":0,"maximum":9007199254740991},"shares":{"type":"integer","minimum":0,"maximum":9007199254740991},"views":{"type":"integer","minimum":0,"maximum":9007199254740991},"source_data":{"description":"Complete public source record returned for this post.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","url"]},{"type":"object","properties":{"url":{"type":"string","format":"uri"},"source_url":{"type":"string","format":"uri"},"handle":{"type":"string"},"display_name":{"type":"string"},"bio":{"type":"string"},"avatar_url":{"type":"string","format":"uri"},"followers":{"type":"integer","minimum":0,"maximum":9007199254740991},"verified":{"type":"boolean"},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["url"]}]}},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."},"has_more":{"default":false,"type":"boolean"}},"required":["network","result_type","results"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/social/transcript":{"post":{"operationId":"social_transcript","summary":"Get social transcript","description":"Get the spoken transcript or captions for one public social video URL.\n\nBest for: Reading or summarizing spoken content from YouTube, TikTok, Instagram, Facebook, and other supported social video pages.\nReturns: Availability status, source and media URLs, transcript text, language, and the normalized public source record.\nQuery tips: Pass the exact public video or post URL. A successful not_available result means no transcript was found.","tags":["Social"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public LinkedIn, Instagram, TikTok, X, YouTube, or Facebook post, video, or reel URL over HTTPS."}},"required":["url"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"network":{"type":"string","enum":["linkedin","instagram","tiktok","x","youtube","facebook"]},"transcript":{"type":"object","properties":{"status":{"type":"string","enum":["available","not_available"]},"source_url":{"type":"string","format":"uri"},"media_url":{"type":"string","format":"uri"},"transcript":{"type":"string"},"language":{"type":"string"},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["status","source_url","media_url","source_data"]}},"required":["network","transcript"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/ads/search":{"post":{"operationId":"ads_search","summary":"Search ads","description":"Search active and historical ads in one public ad library.\n\nBest for: Finding Meta, TikTok, Google, or LinkedIn campaigns by brand, product, slogan, market, date, or media type.\nReturns: Available creative text, advertiser, first and last seen dates, status, media, source records, library URLs, and an opaque next-page cursor.\nQuery tips: Use a brand, product, slogan, or topic as the query. Add country, date, status, or media filters only when required; source support varies.\nNext: Use ads_get on a selected library URL for the complete ad record. Use ads_transcript for spoken Meta video creative.","tags":["Advertising"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"],"description":"Public ad library: Meta, TikTok, Google, or LinkedIn."},"query":{"type":"string","minLength":1,"maxLength":200,"description":"Brand, advertiser, product, slogan, or topic to find, such as 'running shoes' or 'Acme'."},"country":{"description":"Optional two-letter country code, such as 'AT' or 'US'. Omit it for the source default.","type":"string","minLength":2,"maxLength":2},"status":{"description":"Optional ad delivery status, such as 'active' or 'inactive'. Omit it to include any status.","type":"string","maxLength":40},"media_type":{"description":"Optional creative media type, such as 'image' or 'video'. Source support varies.","type":"string","maxLength":40},"start_date":{"description":"Optional earliest ad date in YYYY-MM-DD format.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"description":"Optional latest ad date in YYYY-MM-DD format.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"limit":{"default":20,"description":"Maximum ads to return (1-50, default 20).","type":"integer","minimum":1,"maximum":50},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."}},"required":["platform","query"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"],"description":"Public ad library: Meta, TikTok, Google, or LinkedIn."},"ads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"],"description":"Public ad library: Meta, TikTok, Google, or LinkedIn."},"source_url":{"type":"string","format":"uri"},"advertiser_name":{"type":"string"},"advertiser_url":{"type":"string","format":"uri"},"text":{"default":"","type":"string"},"media_urls":{"default":[],"type":"array","items":{"type":"string","format":"uri"}},"first_seen_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"last_seen_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"active":{"type":"boolean"},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","platform","source_url","source_data"]}},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."},"has_more":{"default":false,"type":"boolean"}},"required":["platform","ads"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/ads/get":{"post":{"operationId":"ads_get","summary":"Get ad","description":"Retrieve one exact public ad from its ad-library URL.\n\nBest for: Inspecting a known Meta, TikTok, Google, or LinkedIn ad after discovery or from a user-supplied URL.\nReturns: Available creative text, advertiser, dates, status, media, source URL, and the normalized public source record.\nQuery tips: Pass the exact public ad-library URL. The platform is detected from the URL.\nNext: Use ads_transcript when a Meta video ad contains spoken content.","tags":["Advertising"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Exact public Meta, TikTok, Google, or LinkedIn ad-library URL over HTTPS."}},"required":["url"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"ad":{"type":"object","properties":{"id":{"type":"string","minLength":1},"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"],"description":"Public ad library: Meta, TikTok, Google, or LinkedIn."},"source_url":{"type":"string","format":"uri"},"advertiser_name":{"type":"string"},"advertiser_url":{"type":"string","format":"uri"},"text":{"default":"","type":"string"},"media_urls":{"default":[],"type":"array","items":{"type":"string","format":"uri"}},"first_seen_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"last_seen_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"active":{"type":"boolean"},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","platform","source_url","source_data"]}},"required":["ad"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/ads/advertiser":{"post":{"operationId":"ads_advertiser","summary":"Search advertisers","description":"Find advertisers, brands, and companies in one public ad library.\n\nBest for: Competitor research and advertiser discovery before listing individual campaigns.\nReturns: Advertiser ID, name, platform, public library URL, source record, and an opaque next-page cursor.\nQuery tips: Use the advertiser or brand name. Add a two-letter country code when the market must be constrained.\nNext: Use ads_search with the selected advertiser name to find its public campaigns.","tags":["Advertising"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"],"description":"Public ad library: Meta, TikTok, Google, or LinkedIn."},"query":{"type":"string","minLength":1,"maxLength":200,"description":"Advertiser, brand, or company name to find, such as 'Acme'."},"country":{"description":"Optional two-letter country code, such as 'AT' or 'US'. Omit it for the source default.","type":"string","minLength":2,"maxLength":2},"limit":{"default":20,"description":"Maximum advertisers to return (1-50, default 20).","type":"integer","minimum":1,"maximum":50},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."}},"required":["platform","query"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"],"description":"Public ad library: Meta, TikTok, Google, or LinkedIn."},"advertisers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"],"description":"Public ad library: Meta, TikTok, Google, or LinkedIn."},"name":{"type":"string","minLength":1},"source_url":{"type":"string","format":"uri"},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","platform","name","source_url","source_data"]}},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."},"has_more":{"default":false,"type":"boolean"}},"required":["platform","advertisers"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/ads/transcript":{"post":{"operationId":"ads_transcript","summary":"Get ad transcript","description":"Get the spoken transcript for one public Meta video ad URL.\n\nBest for: Reading, summarizing, or analyzing spoken advertising creative from a known Meta or Facebook ad.\nReturns: Availability status, source and media URLs, transcript text, language, and the normalized public source record.\nQuery tips: Pass the exact Meta or Facebook ad-library URL. A successful not_available result means no transcript was found.","tags":["Advertising"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Exact public Meta, TikTok, Google, or LinkedIn ad-library URL over HTTPS."}},"required":["url"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"platform":{"type":"string","enum":["meta","tiktok","google","linkedin"],"description":"Public ad library: Meta, TikTok, Google, or LinkedIn."},"transcript":{"type":"object","properties":{"status":{"type":"string","enum":["available","not_available"]},"source_url":{"type":"string","format":"uri"},"media_url":{"type":"string","format":"uri"},"transcript":{"type":"string"},"language":{"type":"string"},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["status","source_url","media_url","source_data"]}},"required":["platform","transcript"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/commerce/search":{"post":{"operationId":"commerce_search","summary":"Search commerce","description":"Search public commerce products by name, category, feature, or shopping need.\n\nBest for: Product discovery, assortment research, pricing research, and finding TikTok Shop listings when no exact URL is known.\nReturns: Available product title, URL, image, price, currency, rating, review count, source record, and an opaque next-page cursor.\nQuery tips: Describe the desired product in natural language. Use region 'US' unless another supported market is required.\nNext: Use commerce_product on a selected URL for exact product detail. Use commerce_reviews for customer feedback.","tags":["Commerce"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"query":{"type":"string","minLength":1,"maxLength":200,"description":"Product name, category, feature, or shopping need to find, such as 'women's trail running shoes'."},"region":{"default":"US","description":"Market or country code used by the platform (default 'US'). Availability varies by platform and tool.","type":"string","minLength":2,"maxLength":8},"limit":{"default":20,"description":"Maximum records to return (1-50, default 20). Reuse the returned cursor for the next page.","type":"integer","minimum":1,"maximum":50},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."}},"required":["platform","query"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"source_url":{"type":"string","format":"uri"},"title":{"type":"string","minLength":1},"image_url":{"type":"string","format":"uri"},"price":{"type":"number","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"rating":{"type":"number","minimum":0,"maximum":5},"review_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","platform","source_url","title","source_data"]}},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."},"has_more":{"default":false,"type":"boolean"}},"required":["platform","products"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/commerce/shop":{"post":{"operationId":"commerce_shop","summary":"Get shop products","description":"List products from one exact public TikTok shop or seller storefront URL.\n\nBest for: Reviewing a known seller's assortment, prices, ratings, and product links.\nReturns: Available product titles, URLs, images, prices, currencies, ratings, review counts, source records, and an opaque next-page cursor.\nQuery tips: Pass the exact public TikTok shop or seller URL and reuse the returned cursor with unchanged inputs for the next page.\nNext: Use commerce_product on a selected product URL for exact detail. Use commerce_reviews for customer feedback.","tags":["Commerce"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"url":{"type":"string","format":"uri","description":"Exact public TikTok shop or seller storefront URL over HTTPS."},"region":{"default":"US","description":"Market or country code used by the platform (default 'US'). Availability varies by platform and tool.","type":"string","minLength":2,"maxLength":8},"limit":{"default":20,"description":"Maximum records to return (1-50, default 20). Reuse the returned cursor for the next page.","type":"integer","minimum":1,"maximum":50},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."}},"required":["platform","url"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"source_url":{"type":"string","format":"uri"},"title":{"type":"string","minLength":1},"image_url":{"type":"string","format":"uri"},"price":{"type":"number","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"rating":{"type":"number","minimum":0,"maximum":5},"review_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","platform","source_url","title","source_data"]}},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."},"has_more":{"default":false,"type":"boolean"}},"required":["platform","products"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/commerce/product":{"post":{"operationId":"commerce_product","summary":"Get product","description":"Retrieve one exact public commerce product from its URL.\n\nBest for: Inspecting a known product after commerce_search, commerce_shop, or commerce_creator_shop.\nReturns: Available product title, source URL, image, price, currency, rating, review count, and the normalized public source record.\nQuery tips: Pass the exact public product-detail URL. TikTok product detail currently requires region 'US'.\nNext: Use commerce_reviews on the same product URL for customer ratings and review text.","tags":["Commerce"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"url":{"type":"string","format":"uri","description":"Exact public product-detail URL over HTTPS. TikTok product detail currently requires region 'US'."},"region":{"default":"US","description":"Market or country code used by the platform (default 'US'). Availability varies by platform and tool.","type":"string","minLength":2,"maxLength":8}},"required":["platform","url"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"product":{"type":"object","properties":{"id":{"type":"string","minLength":1},"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"source_url":{"type":"string","format":"uri"},"title":{"type":"string","minLength":1},"image_url":{"type":"string","format":"uri"},"price":{"type":"number","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"rating":{"type":"number","minimum":0,"maximum":5},"review_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","platform","source_url","title","source_data"]}},"required":["product"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/commerce/reviews":{"post":{"operationId":"commerce_reviews","summary":"Get product reviews","description":"List public customer ratings and review text for one exact product URL.\n\nBest for: Product feedback, sentiment, complaints, purchase research, and evidence from public review pages.\nReturns: Review text, rating, author, date, source record, and an opaque next-page cursor when available.\nQuery tips: Pass the exact product-detail URL and reuse the returned cursor with unchanged inputs for the next page.","tags":["Commerce"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"url":{"type":"string","format":"uri","description":"Exact public product-detail URL whose customer reviews should be listed."},"region":{"default":"US","description":"Market or country code used by the platform (default 'US'). Availability varies by platform and tool.","type":"string","minLength":2,"maxLength":8},"limit":{"default":20,"description":"Maximum records to return (1-50, default 20). Reuse the returned cursor for the next page.","type":"integer","minimum":1,"maximum":50},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."}},"required":["platform","url"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"product_url":{"type":"string","format":"uri"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"text":{"default":"","type":"string"},"rating":{"type":"number","minimum":0,"maximum":5},"author_name":{"type":"string"},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","source_data"]}},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."},"has_more":{"default":false,"type":"boolean"}},"required":["platform","product_url","reviews"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/commerce/creator_shop":{"post":{"operationId":"commerce_creator_shop","summary":"Get creator shop","description":"List products from one TikTok creator showcase or Amazon influencer storefront.\n\nBest for: Creator commerce, affiliate assortment, sponsorship research, and reviewing products promoted by a known creator.\nReturns: Available product titles, URLs, images, prices, currencies, ratings, review counts, source records, and an opaque next-page cursor.\nQuery tips: Provide a public storefront URL. A TikTok creator handle without '@' also works when no URL is available.\nNext: Use commerce_product on a selected TikTok product URL for exact detail.","tags":["Commerce"],"security":[{"apiKey":[]},{"oauth2":["capabilities:execute"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Replay-safe key scoped to the workspace and verified credential.","schema":{"type":"string","minLength":8,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"url":{"description":"Public TikTok creator showcase or Amazon influencer storefront URL. Provide this or handle.","type":"string","format":"uri"},"handle":{"description":"TikTok creator username, with or without '@'. Provide this or url.","type":"string","minLength":1,"maxLength":120},"region":{"default":"US","description":"Market or country code used by the platform (default 'US'). Availability varies by platform and tool.","type":"string","minLength":2,"maxLength":8},"limit":{"default":20,"description":"Maximum records to return (1-50, default 20). Reuse the returned cursor for the next page.","type":"integer","minimum":1,"maximum":50},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."}},"required":["platform"]}}}},"responses":{"200":{"description":"Normalized result and execution metadata.","content":{"application/json":{"schema":{"type":"object","required":["request_id","data_fetched_at","cache_status","result"],"properties":{"request_id":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"cache_status":{"type":"string","enum":["hit","miss"]},"result":{"type":"object","properties":{"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"platform":{"type":"string","enum":["tiktok","amazon"],"description":"Commerce platform. TikTok supports all commerce tools; Amazon supports commerce_creator_shop only."},"source_url":{"type":"string","format":"uri"},"title":{"type":"string","minLength":1},"image_url":{"type":"string","format":"uri"},"price":{"type":"number","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"rating":{"type":"number","minimum":0,"maximum":5},"review_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"source_data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","platform","source_url","title","source_data"]}},"cursor":{"type":"string","minLength":1,"maxLength":4096,"description":"Opaque cursor from the previous response. Reuse it only with the same tool and unchanged filters."},"has_more":{"default":false,"type":"boolean"}},"required":["platform","products"]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/capabilities":{"get":{"operationId":"listCapabilities","tags":["Metadata"],"security":[],"responses":{"200":{"description":"Public capability catalog"}}}},"/v1/quotes":{"post":{"operationId":"getCreditQuote","tags":["Metadata"],"security":[{"apiKey":[]},{"oauth2":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"capability":{"type":"string","minLength":1,"description":"Exact capability id, such as 'web.search', 'social.search', or 'ads.search'."},"input":{"description":"The exact input you intend to send to the capability."}},"required":["capability","input"]}}}},"responses":{"200":{"description":"Deterministic credit quote","content":{"application/json":{"schema":{"type":"object","properties":{"capability":{"type":"string"},"credits":{"type":"integer","minimum":0,"maximum":9007199254740991},"price_version":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["capability","credits","price_version"]}}}}}}},"/v1/usage":{"get":{"operationId":"getUsage","tags":["Usage"],"security":[{"apiKey":[]},{"oauth2":[]}],"responses":{"200":{"description":"Wallet and ledger summary","content":{"application/json":{"schema":{"type":"object","properties":{"credits_remaining":{"type":"integer","minimum":0,"maximum":9007199254740991},"calls_30d":{"type":"integer","minimum":0,"maximum":9007199254740991},"credits_30d":{"type":"integer","minimum":0,"maximum":9007199254740991},"action_breakdown":{"type":"array","items":{"type":"object","properties":{"capability":{"type":"string"},"calls":{"type":"integer","minimum":0,"maximum":9007199254740991},"credits":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["capability","calls","credits"]}},"buckets":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["trial","subscription","purchased","promotional"]},"credits_available":{"type":"integer","minimum":0,"maximum":9007199254740991},"expires_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]}},"required":["kind","credits_available","expires_at"]}},"recent_executions":{"type":"array","items":{"type":"object","properties":{"request_id":{"type":"string"},"capability":{"type":"string"},"credits_charged":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["succeeded","failed"]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"cache_status":{"type":"string","enum":["hit","miss"]},"data_fetched_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"result":{}},"required":["request_id","capability","credits_charged","status","created_at"]}}},"required":["credits_remaining","calls_30d","credits_30d","action_breakdown","buckets","recent_executions"]}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://supercenter.dev/api/auth/oauth2/authorize","tokenUrl":"https://supercenter.dev/api/auth/oauth2/token","refreshUrl":"https://supercenter.dev/api/auth/oauth2/token","scopes":{"capabilities:execute":"Execute capabilities","usage:read":"Read usage"}}}}},"responses":{"Error":{"description":"Customer-safe error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","plan_upgrade_required","payment_required","insufficient_credits","not_found","conflict","unsupported","rate_limited","temporarily_unavailable","internal_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}},"Unauthorized":{"description":"Missing or invalid credentials","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","plan_upgrade_required","payment_required","insufficient_credits","not_found","conflict","unsupported","rate_limited","temporarily_unavailable","internal_error"]},"message":{"type":"string"},"request_id":{"type":"string"}}}}}}}}}}}