{"openapi":"3.1.0","info":{"title":"Media Cloud (BYOK) API","version":"0.1.0","description":"Media Cloud (BYOK) lets an AI assistant read your own Media Cloud data through the Media Cloud API with a key you supply (API key). Read-only: 10 tools (count_matching_stories, story_counts_over_time, list_stories, top_sources, language_mix, get_story, list_collections, get_collection, list_sources, get_source). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-mediacloud.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-mediacloud/docs"},"termsOfService":"https://connectorbay.com/byok-mediacloud/terms"},"servers":[{"url":"https://byok-mediacloud.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-mediacloud/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/count_matching_stories":{"post":{"operationId":"count_matching_stories","summary":"Count how many news stories match a query in a date range, and how many stories were indexed in total in that range. Med","description":"Count how many news stories match a query in a date range, and how many stories were indexed in total in that range. Media Cloud rate-limits requests per minute and is meant for academic, nonprofit and journalistic research. Use for \"How many news stories mentioned climate change in September\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Media Cloud boolean query, for example '\"climate change\" AND (policy OR law)'. Phrases go in double quotes; AND, OR, NOT are supported.","maxLength":1000,"title":"Q","type":"string"},"start":{"description":"First day to search, YYYY-MM-DD.","maxLength":10,"title":"Start","type":"string"},"end":{"description":"Last day to search, YYYY-MM-DD.","maxLength":10,"title":"End","type":"string"},"collection_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated collection IDs to search within (from list_collections), for example '34412234'. Name at least one collection or source to keep the search meaningful.","title":"Collection Ids"},"source_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated source IDs to search within (from list_sources).","title":"Source Ids"},"platform":{"anyOf":[{"const":"onlinenews-mediacloud","type":"string"},{"type":"null"}],"default":"onlinenews-mediacloud","description":"Which news index to search; only the main Media Cloud online news archive is offered here.","title":"Platform"}},"required":["q","start","end"],"title":"count_matching_storiesArguments","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/story_counts_over_time":{"post":{"operationId":"story_counts_over_time","summary":"Get the number of matching stories per day for a query, with the total stories indexed that day and the ratio. Media Clo","description":"Get the number of matching stories per day for a query, with the total stories indexed that day and the ratio. Media Cloud rate-limits requests per minute and is meant for academic, nonprofit and journalistic research. Use for \"How did coverage of climate change trend during September\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Media Cloud boolean query, for example '\"climate change\" AND (policy OR law)'. Phrases go in double quotes; AND, OR, NOT are supported.","maxLength":1000,"title":"Q","type":"string"},"start":{"description":"First day to search, YYYY-MM-DD.","maxLength":10,"title":"Start","type":"string"},"end":{"description":"Last day to search, YYYY-MM-DD.","maxLength":10,"title":"End","type":"string"},"collection_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated collection IDs to search within (from list_collections), for example '34412234'. Name at least one collection or source to keep the search meaningful.","title":"Collection Ids"},"source_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated source IDs to search within (from list_sources).","title":"Source Ids"},"platform":{"anyOf":[{"const":"onlinenews-mediacloud","type":"string"},{"type":"null"}],"default":"onlinenews-mediacloud","description":"Which news index to search; only the main Media Cloud online news archive is offered here.","title":"Platform"}},"required":["q","start","end"],"title":"story_counts_over_timeArguments","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/list_stories":{"post":{"operationId":"list_stories","summary":"List stories matching a query with title, link, outlet, language and dates (no article text). Page with the pagination t","description":"List stories matching a query with title, link, outlet, language and dates (no article text). Page with the pagination token. Media Cloud rate-limits requests per minute and is meant for academic, nonprofit and journalistic research. Use for \"Which news stories covered the city climate plan this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Media Cloud boolean query, for example '\"climate change\" AND (policy OR law)'. Phrases go in double quotes; AND, OR, NOT are supported.","maxLength":1000,"title":"Q","type":"string"},"start":{"description":"First day to search, YYYY-MM-DD.","maxLength":10,"title":"Start","type":"string"},"end":{"description":"Last day to search, YYYY-MM-DD.","maxLength":10,"title":"End","type":"string"},"collection_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated collection IDs to search within (from list_collections), for example '34412234'. Name at least one collection or source to keep the search meaningful.","title":"Collection Ids"},"source_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated source IDs to search within (from list_sources).","title":"Source Ids"},"platform":{"anyOf":[{"const":"onlinenews-mediacloud","type":"string"},{"type":"null"}],"default":"onlinenews-mediacloud","description":"Which news index to search; only the main Media Cloud online news archive is offered here.","title":"Platform"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Stories per page (1 to 100).","title":"Page Size"},"pagination_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Token for the next page: pagination_token from the previous answer. Leave out for the first page.","title":"Pagination Token"}},"required":["q","start","end"],"title":"list_storiesArguments","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/top_sources":{"post":{"operationId":"top_sources","summary":"List the news outlets that published the most stories matching a query, with story counts. Media Cloud rate-limits reque","description":"List the news outlets that published the most stories matching a query, with story counts. Media Cloud rate-limits requests per minute and is meant for academic, nonprofit and journalistic research. Use for \"Which outlets wrote most about climate change in September\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Media Cloud boolean query, for example '\"climate change\" AND (policy OR law)'. Phrases go in double quotes; AND, OR, NOT are supported.","maxLength":1000,"title":"Q","type":"string"},"start":{"description":"First day to search, YYYY-MM-DD.","maxLength":10,"title":"Start","type":"string"},"end":{"description":"Last day to search, YYYY-MM-DD.","maxLength":10,"title":"End","type":"string"},"collection_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated collection IDs to search within (from list_collections), for example '34412234'. Name at least one collection or source to keep the search meaningful.","title":"Collection Ids"},"source_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated source IDs to search within (from list_sources).","title":"Source Ids"},"platform":{"anyOf":[{"const":"onlinenews-mediacloud","type":"string"},{"type":"null"}],"default":"onlinenews-mediacloud","description":"Which news index to search; only the main Media Cloud online news archive is offered here.","title":"Platform"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many outlets to return (1 to 100).","title":"Limit"}},"required":["q","start","end"],"title":"top_sourcesArguments","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/language_mix":{"post":{"operationId":"language_mix","summary":"Show which languages the stories matching a query are written in, as a share and a count. Media Cloud rate-limits reques","description":"Show which languages the stories matching a query are written in, as a share and a count. Media Cloud rate-limits requests per minute and is meant for academic, nonprofit and journalistic research. Use for \"In which languages was climate change covered in September\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"description":"Media Cloud boolean query, for example '\"climate change\" AND (policy OR law)'. Phrases go in double quotes; AND, OR, NOT are supported.","maxLength":1000,"title":"Q","type":"string"},"start":{"description":"First day to search, YYYY-MM-DD.","maxLength":10,"title":"Start","type":"string"},"end":{"description":"Last day to search, YYYY-MM-DD.","maxLength":10,"title":"End","type":"string"},"collection_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated collection IDs to search within (from list_collections), for example '34412234'. Name at least one collection or source to keep the search meaningful.","title":"Collection Ids"},"source_ids":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated source IDs to search within (from list_sources).","title":"Source Ids"},"platform":{"anyOf":[{"const":"onlinenews-mediacloud","type":"string"},{"type":"null"}],"default":"onlinenews-mediacloud","description":"Which news index to search; only the main Media Cloud online news archive is offered here.","title":"Platform"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many languages to return (1 to 50).","title":"Limit"}},"required":["q","start","end"],"title":"language_mixArguments","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_story":{"post":{"operationId":"get_story","summary":"Get one story's metadata by its Media Cloud story ID: title, link, outlet, language, publish and index dates. Media Clou","description":"Get one story's metadata by its Media Cloud story ID: title, link, outlet, language, publish and index dates. Media Cloud rate-limits requests per minute and is meant for academic, nonprofit and journalistic research. Use for \"Show Media Cloud story abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"story_id":{"description":"Story ID as returned by list_stories (id).","maxLength":200,"title":"Story Id","type":"string"},"platform":{"anyOf":[{"const":"onlinenews-mediacloud","type":"string"},{"type":"null"}],"default":"onlinenews-mediacloud","description":"Which news index to search; only the main Media Cloud online news archive is offered here.","title":"Platform"}},"required":["story_id"],"title":"get_storyArguments","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/list_collections":{"post":{"operationId":"list_collections","summary":"List Media Cloud collections (curated groups of news outlets) with ID, name, platform and notes. Search by name; use the","description":"List Media Cloud collections (curated groups of news outlets) with ID, name, platform and notes. Search by name; use the IDs in the search tools. Media Cloud rate-limits requests per minute and is meant for academic, nonprofit and journalistic research. Use for \"Which Media Cloud collections cover US national news\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only collections whose name contains this text.","title":"Name"},"platform":{"anyOf":[{"enum":["online_news","youtube","twitter","reddit"],"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this platform.","title":"Platform"},"source_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only collections containing this source ID.","title":"Source Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip, for paging.","title":"Offset"}},"title":"list_collectionsArguments","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_collection":{"post":{"operationId":"get_collection","summary":"Get one Media Cloud collection by ID: name, platform, notes and flags. Media Cloud rate-limits requests per minute and i","description":"Get one Media Cloud collection by ID: name, platform, notes and flags. Media Cloud rate-limits requests per minute and is meant for academic, nonprofit and journalistic research. Use for \"What is Media Cloud collection 34412234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"collection_id":{"description":"Collection ID as returned by list_collections (id).","minimum":1,"title":"Collection Id","type":"integer"}},"required":["collection_id"],"title":"get_collectionArguments","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/list_sources":{"post":{"operationId":"list_sources","summary":"List Media Cloud sources (news outlets) with ID, name, homepage, media type, country and language. Filter by name or col","description":"List Media Cloud sources (news outlets) with ID, name, homepage, media type, country and language. Filter by name or collection. Media Cloud rate-limits requests per minute and is meant for academic, nonprofit and journalistic research. Use for \"Which news outlets are in Media Cloud collection 34412234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only sources whose name contains this text.","title":"Name"},"platform":{"anyOf":[{"enum":["online_news","youtube","twitter","reddit"],"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this platform.","title":"Platform"},"collection_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only sources in this collection ID.","title":"Collection Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many records to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many records to skip, for paging.","title":"Offset"}},"title":"list_sourcesArguments","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_source":{"post":{"operationId":"get_source","summary":"Get one Media Cloud source (news outlet) by ID: name, label, homepage, media type, country and primary language. Media C","description":"Get one Media Cloud source (news outlet) by ID: name, label, homepage, media type, country and primary language. Media Cloud rate-limits requests per minute and is meant for academic, nonprofit and journalistic research. Use for \"What is Media Cloud source 1001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"source_id":{"description":"Source ID as returned by list_sources (id).","minimum":1,"title":"Source Id","type":"integer"}},"required":["source_id"],"title":"get_sourceArguments","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}}}}