{"openapi":"3.1.0","info":{"title":"APITube (BYOK) API","version":"0.1.0","description":"APITube (BYOK) lets an AI assistant read your own APITube data through the APITube API with a key you supply (APITube API key). Read-only: 9 tools (search_news, get_top_headlines, count_news, get_news_trends, suggest_entities, get_news_by_entity, search_companies, get_company, get_balance). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-apitube.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-apitube/docs"},"termsOfService":"https://connectorbay.com/byok-apitube/terms"},"servers":[{"url":"https://byok-apitube.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-apitube/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_news":{"post":{"operationId":"search_news","summary":"Search the news archive by title words and filters (language, dates, publisher, people, organizations, sentiment, catego","description":"Search the news archive by title words and filters (language, dates, publisher, people, organizations, sentiment, category); each article carries a sentiment score. Costs 1 plan point per call; the Free plan sees articles 12 hours after publication. Use for \"Find positive English news about Tesla from the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words to find in article titles, for example 'bitcoin'. Title searches cover at most 31 days.","title":"Title"},"language_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Language code(s), comma separated, at most 3, for example 'en'.","title":"Language Code"},"published_start":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest publication date, YYYY-MM-DD or ISO 8601 (a title search covers at most 31 days).","title":"Published Start"},"published_end":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Latest publication date, YYYY-MM-DD or ISO 8601.","title":"Published End"},"source_domain":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Publisher domain(s), comma separated, at most 3, for example 'nytimes.com'.","title":"Source Domain"},"source_country_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Publisher country code(s), two letters, at most 3, for example 'us'.","title":"Source Country Code"},"organization_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Organization name(s) mentioned, comma separated, at most 3, for example 'Tesla'.","title":"Organization Name"},"person_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Person name(s) mentioned, comma separated, at most 3, for example 'Elon Musk'.","title":"Person Name"},"sentiment_polarity":{"anyOf":[{"enum":["positive","negative","neutral"],"type":"string"},{"type":"null"}],"default":null,"description":"Overall tone of the article: positive, negative or neutral.","title":"Sentiment Polarity"},"category_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"IPTC Media Topic category id(s), at most 3, for example 'medtop:04000000' (economy, business and finance).","title":"Category Id"},"sort_by":{"anyOf":[{"enum":["published_at","relevance","engagement","quality","controversy","trust","sentiment.overall.score"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: published_at (default), relevance, engagement, quality, controversy, trust or sentiment.overall.score.","title":"Sort By"},"sort_order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Direction: desc (default) or asc.","title":"Sort Order"},"per_page":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page, 1 to 250 (the plan limits it: Free 10, Starter 50, Basic 200).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the Free plan stops at page 5).","title":"Page"}},"title":"search_newsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_top_headlines":{"post":{"operationId":"get_top_headlines","summary":"Get current headlines from highly ranked publishers (Open Page Rank 5 or above) with the same filters as the search. Cos","description":"Get current headlines from highly ranked publishers (Open Page Rank 5 or above) with the same filters as the search. Costs 1 plan point per call. Use for \"What are the top US headlines right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"language_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Language code(s), comma separated, at most 3, for example 'en'.","title":"Language Code"},"published_start":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest publication date, YYYY-MM-DD or ISO 8601 (a title search covers at most 31 days).","title":"Published Start"},"published_end":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Latest publication date, YYYY-MM-DD or ISO 8601.","title":"Published End"},"source_domain":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Publisher domain(s), comma separated, at most 3, for example 'nytimes.com'.","title":"Source Domain"},"source_country_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Publisher country code(s), two letters, at most 3, for example 'us'.","title":"Source Country Code"},"organization_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Organization name(s) mentioned, comma separated, at most 3, for example 'Tesla'.","title":"Organization Name"},"person_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Person name(s) mentioned, comma separated, at most 3, for example 'Elon Musk'.","title":"Person Name"},"sentiment_polarity":{"anyOf":[{"enum":["positive","negative","neutral"],"type":"string"},{"type":"null"}],"default":null,"description":"Overall tone of the article: positive, negative or neutral.","title":"Sentiment Polarity"},"category_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"IPTC Media Topic category id(s), at most 3, for example 'medtop:04000000' (economy, business and finance).","title":"Category Id"},"per_page":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page, 1 to 250 (the plan limits it: Free 10, Starter 50, Basic 200).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the Free plan stops at page 5).","title":"Page"}},"title":"get_top_headlinesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/count_news":{"post":{"operationId":"count_news","summary":"Count the articles that match a title word or filters without loading them, for example to compare coverage volume or to","description":"Count the articles that match a title word or filters without loading them, for example to compare coverage volume or tone. Use for \"How many negative articles mention Tesla this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Words to find in article titles.","title":"Title"},"language_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Language code(s), comma separated, at most 3, for example 'en'.","title":"Language Code"},"published_start":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest publication date, YYYY-MM-DD or ISO 8601 (a title search covers at most 31 days).","title":"Published Start"},"published_end":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Latest publication date, YYYY-MM-DD or ISO 8601.","title":"Published End"},"source_domain":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Publisher domain(s), comma separated, at most 3, for example 'nytimes.com'.","title":"Source Domain"},"source_country_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Publisher country code(s), two letters, at most 3, for example 'us'.","title":"Source Country Code"},"organization_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Organization name(s) mentioned, comma separated, at most 3, for example 'Tesla'.","title":"Organization Name"},"person_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Person name(s) mentioned, comma separated, at most 3, for example 'Elon Musk'.","title":"Person Name"},"sentiment_polarity":{"anyOf":[{"enum":["positive","negative","neutral"],"type":"string"},{"type":"null"}],"default":null,"description":"Overall tone of the article: positive, negative or neutral.","title":"Sentiment Polarity"},"category_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"IPTC Media Topic category id(s), at most 3, for example 'medtop:04000000' (economy, business and finance).","title":"Category Id"}},"title":"count_newsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_news_trends":{"post":{"operationId":"get_news_trends","summary":"Rank the most mentioned entities, categories, topics, industries or publishers in the news with counts, share and option","description":"Rank the most mentioned entities, categories, topics, industries or publishers in the news with counts, share and optional growth rate. Use for \"Which companies and people are trending in the news this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"field":{"description":"What to rank: entity.id, category.id, topic.id, industry.id or source.id.","enum":["entity.id","category.id","topic.id","industry.id","source.id"],"title":"Field","type":"string"},"trending":{"anyOf":[{"enum":["0","1"],"type":"string"},{"type":"null"}],"default":null,"description":"1 to add growth_rate and trending_score over the last trending_days days.","title":"Trending"},"trending_days":{"anyOf":[{"maximum":30,"minimum":7,"type":"integer"},{"type":"null"}],"default":null,"description":"Days used for the trend analysis, 7 to 30 (default 14).","title":"Trending Days"},"sort":{"anyOf":[{"enum":["count","value","growth_rate","change","trending_score"],"type":"string"},{"type":"null"}],"default":null,"description":"Order by count (default), value, growth_rate, change or trending_score.","title":"Sort"},"language_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Language code(s), comma separated, at most 3, for example 'en'.","title":"Language Code"},"published_start":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest publication date, YYYY-MM-DD or ISO 8601.","title":"Published Start"},"published_end":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Latest publication date, YYYY-MM-DD or ISO 8601.","title":"Published End"},"per_page":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Number of ranked values to return, 1 to 250.","title":"Per Page"}},"required":["field"],"title":"get_news_trendsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/suggest_entities":{"post":{"operationId":"suggest_entities","summary":"Find people, organizations, brands, places and products by the start of their name, returning the entity id, type and Wi","description":"Find people, organizations, brands, places and products by the start of their name, returning the entity id, type and Wikipedia link used by the entity filters. Use for \"What is the APITube entity id for Tesla\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"description":"Start of the entity name, at least 1 character, for example 'Tesla'.","maxLength":100,"title":"Prefix","type":"string"}},"required":["prefix"],"title":"suggest_entitiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_news_by_entity":{"post":{"operationId":"get_news_by_entity","summary":"List articles about one known entity (person, company, brand, place) by its numeric entity id. Costs 1 plan point per ca","description":"List articles about one known entity (person, company, brand, place) by its numeric entity id. Costs 1 plan point per call. Use for \"Show recent news about entity 474\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"entity_id":{"description":"Numeric entity id, found with suggest_entities.","minimum":0,"title":"Entity Id","type":"integer"},"language_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Language code(s), comma separated, at most 3, for example 'en'.","title":"Language Code"},"published_start":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest publication date, YYYY-MM-DD or ISO 8601 (a title search covers at most 31 days).","title":"Published Start"},"published_end":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Latest publication date, YYYY-MM-DD or ISO 8601.","title":"Published End"},"source_domain":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Publisher domain(s), comma separated, at most 3, for example 'nytimes.com'.","title":"Source Domain"},"source_country_code":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Publisher country code(s), two letters, at most 3, for example 'us'.","title":"Source Country Code"},"per_page":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page, 1 to 250 (the plan limits it: Free 10, Starter 50, Basic 200).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the Free plan stops at page 5).","title":"Page"}},"required":["entity_id"],"title":"get_news_by_entityArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_companies":{"post":{"operationId":"search_companies","summary":"Search company and brand profiles in the news directory by name, with description and website. Use for \"Look up Tesla in","description":"Search company and brand profiles in the news directory by name, with description and website. Use for \"Look up Tesla in the company directory\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Company name (substring match), for example 'Tesla'.","title":"Name"},"wikidata_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Wikidata id such as Q478214.","title":"Wikidata Id"},"per_page":{"anyOf":[{"maximum":250,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page, 1 to 250 (the plan limits it: Free 10, Starter 50, Basic 200).","title":"Per Page"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (the Free plan stops at page 5).","title":"Page"}},"title":"search_companiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_company":{"post":{"operationId":"get_company","summary":"Get one company's directory profile by numeric id, with its news coverage summary (article count, sentiment, momentum). ","description":"Get one company's directory profile by numeric id, with its news coverage summary (article count, sentiment, momentum). Use for \"What is the news coverage profile of company 474\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"company_id":{"description":"Numeric company id, from search_companies.","minimum":0,"title":"Company Id","type":"integer"}},"required":["company_id"],"title":"get_companyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_balance":{"post":{"operationId":"get_balance","summary":"Show the plan and remaining points of the API key. This call is free and uses no points. Use for \"How many APITube point","description":"Show the plan and remaining points of the API key. This call is free and uses no points. Use for \"How many APITube points do I have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_balanceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}