{"openapi":"3.1.0","info":{"title":"Perigon (BYOK) API","version":"0.1.0","description":"Perigon (BYOK) lets an AI assistant read your own Perigon data through the Perigon API with a key you supply (Perigon API key). Read-only: 8 tools (search_articles, search_stories, search_sources, search_journalists, search_companies, search_people, list_topics, get_usage_limits). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-perigon.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-perigon/docs"},"termsOfService":"https://connectorbay.com/byok-perigon/terms"},"servers":[{"url":"https://byok-perigon.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-perigon/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_articles":{"post":{"operationId":"search_articles","summary":"Search news articles with Boolean query syntax and filters (source domain, language, country, category, topic, company t","description":"Search news articles with Boolean query syntax and filters (source domain, language, country, category, topic, company ticker, date range). Returns title, description, AI summary, URL, publish date, source domain, byline and sentiment. Each call counts against the monthly request quota. Use for \"What news was published this week about Nvidia\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search query over title, description and content; supports AND, OR, NOT and quoted phrases.","title":"Q"},"title":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search only inside headlines.","title":"Title"},"published_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published after this date (ISO 8601 such as 2026-01-01 or 2026-01-01T00:00:00).","title":"Published From"},"published_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles published before this date (ISO 8601).","title":"Published To"},"source":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles from this publisher domain, for example 'reuters.com'.","title":"Source"},"language":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles in this ISO 639-1 language code, for example 'en'.","title":"Language"},"country":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles from this country code, for example 'us'.","title":"Country"},"category":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Only this category, for example Tech, Politics or Business.","title":"Category"},"topic":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only this topic, for example Markets or Cryptocurrency.","title":"Topic"},"company_symbol":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":null,"description":"Only articles about the company with this stock ticker, for example NVDA.","title":"Company Symbol"},"sort_by":{"anyOf":[{"enum":["relevance","date","reverseDate","reverseAddDate","addDate","pubDate"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: relevance, date (newest first), reverseDate, addDate or pubDate.","title":"Sort By"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"},"show_num_results":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also return the exact number of matches (slower).","title":"Show Num Results"}},"title":"search_articlesArguments","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_stories":{"post":{"operationId":"search_stories","summary":"Search stories, which are clusters of articles about the same event, with AI summary, article counts, unique sources and","description":"Search stories, which are clusters of articles about the same event, with AI summary, article counts, unique sources and top countries. Use for \"What are the biggest news stories about elections today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search query over story names and summaries; supports Boolean operators.","title":"Q"},"published_from":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only stories created on or after this date (ISO 8601).","title":"Published From"},"published_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only stories created on or before this date (ISO 8601).","title":"Published To"},"topic":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only this topic, for example Markets.","title":"Topic"},"category":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Only this category, for example Politics.","title":"Category"},"country":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Only this country code, for example 'us'.","title":"Country"},"sort_by":{"anyOf":[{"enum":["createdAt","updatedAt","relevance","count","totalCount"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: createdAt, updatedAt, relevance, count or totalCount.","title":"Sort By"},"min_unique_sources":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only stories covered by at least this many distinct sources.","title":"Min Unique Sources"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"},"show_num_results":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to also return the exact number of matches (slower).","title":"Show Num Results"}},"title":"search_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/search_sources":{"post":{"operationId":"search_sources","summary":"Search the news publishers Perigon indexes by name or domain, with country, category, traffic rank, paywall flag and pub","description":"Search the news publishers Perigon indexes by name or domain, with country, category, traffic rank, paywall flag and published bias ratings. Use for \"Which news sources cover technology in Germany\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Source name to search for.","title":"Name"},"domain":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Exact publisher domain, for example 'bbc.co.uk'.","title":"Domain"},"country":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Sources that cover this country code, for example 'de'.","title":"Country"},"category":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Sources whose main category is this, for example Tech.","title":"Category"},"topic":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Sources that frequently cover this topic.","title":"Topic"},"sort_by":{"anyOf":[{"enum":["globalRank","relevance","monthlyVisits","avgMonthlyPosts"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: globalRank, relevance, monthlyVisits or avgMonthlyPosts.","title":"Sort By"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"}},"title":"search_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/search_journalists":{"post":{"operationId":"search_journalists","summary":"Search journalist profiles by name, outlet, topic, category or country, with headline, publishing volume and public prof","description":"Search journalist profiles by name, outlet, topic, category or country, with headline, publishing volume and public profile links. Email addresses are not returned. Use for \"Which journalists cover cybersecurity for wired.com\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Journalist name to search for.","title":"Name"},"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text query over the journalist profile.","title":"Q"},"source":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Journalists writing for this publisher domain.","title":"Source"},"topic":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Journalists who mainly cover this topic.","title":"Topic"},"category":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Journalists who mainly cover this category.","title":"Category"},"country":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Journalists covering this country code.","title":"Country"},"sort_by":{"anyOf":[{"enum":["avgMonthlyPosts","linkedinConnections","linkedinFollowers"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: avgMonthlyPosts, linkedinConnections or linkedinFollowers.","title":"Sort By"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"}},"title":"search_journalistsArguments","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 the company directory by name, ticker, domain, industry, sector or country, returning description, CEO, headcount","description":"Search the company directory by name, ticker, domain, industry, sector or country, returning description, CEO, headcount, founding year, ISIN and ticker symbols. Use for \"What do you know about the company with ticker NVDA\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free-text query over company names and descriptions.","title":"Q"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Company name to search for.","title":"Name"},"symbol":{"anyOf":[{"maxLength":12,"type":"string"},{"type":"null"}],"default":null,"description":"Exact stock ticker symbol, for example 'NVDA'.","title":"Symbol"},"domain":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Company website domain, for example 'nvidia.com'.","title":"Domain"},"industry":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Industry classification to match.","title":"Industry"},"sector":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Sector classification to match.","title":"Sector"},"country":{"anyOf":[{"maxLength":5,"type":"string"},{"type":"null"}],"default":null,"description":"Headquarters country code.","title":"Country"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"}},"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/search_people":{"post":{"operationId":"search_people","summary":"Search public figures by name or occupation, returning description, aliases, occupations, positions and a short abstract","description":"Search public figures by name or occupation, returning description, aliases, occupations, positions and a short abstract. Use for \"Who is the public figure named Satya Nadella\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Person name to search for.","title":"Name"},"occupation_label":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Occupation to match, for example politician or CEO.","title":"Occupation Label"},"wikidata_id":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Exact Wikidata id, for example Q7747.","title":"Wikidata Id"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"}},"title":"search_peopleArguments","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_topics":{"post":{"operationId":"list_topics","summary":"List the topic tags Perigon assigns to articles, optionally filtered by name or category. Use for \"Which topics does Per","description":"List the topic tags Perigon assigns to articles, optionally filtered by name or category. Use for \"Which topics does Perigon use for technology news\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Topic name or part of it.","title":"Name"},"category":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Broad category such as Politics or Tech.","title":"Category"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many topics per page (1 to 1000).","title":"Size"}},"title":"list_topicsArguments","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_usage_limits":{"post":{"operationId":"get_usage_limits","summary":"Show the key's organization name, requests used and allowed this period, maximum page size and reset date. Use for \"How ","description":"Show the key's organization name, requests used and allowed this period, maximum page size and reset date. Use for \"How many Perigon requests have I used this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_usage_limitsArguments","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}}}}