Perigon TypeScript SDK
TypeScript client for the Perigon API
A fully-typed, promise-based SDK generated from the official Perigon OpenAPI specification. Works in Node.js, modern browsers, Cloudflare Workers, and Deno.
## Table of Contents
- [β¨ Features](#-features)
- [π¦ Installation](#-installation)
- [π Quick start](#-quick-start)
- [π§βπ» Endpoint snippets](#-endpoint-snippets)
- [πͺͺ License](#-license)
---
## β¨ Features
- **Type-safe** request/response models (goodbye `any`)
- Ships as both **ESM & CommonJS** with sourcemaps
- **Zero-dependency core** β bring your own `fetch` if needed
- Generated directly from [docs.perigon.io](https://docs.perigon.io), so itβs always in sync
- Runs in **Node, browsers, Deno, and edge runtimes**
---
## π¦ Installation
```bash
npm install @goperigon/perigon-ts
# yarn add @goperigon/perigon-ts
# pnpm add @goperigon/perigon-ts
```
---
## π Quick start
### 1. Instantiate the client
```ts
import { Configuration, V1Api } from "@goperigon/perigon-ts";
const perigon = new V1Api(
new Configuration({
apiKey: "YOUR_API_KEY", // or () => 'your_key'
// basePath: 'https://api.perigon.io', // override for proxy / dev
}),
);
```
### 2. Make calls
```ts
// π Search recent news articles
const { articles, numResults } = await perigon.searchArticles({
q: "artificial intelligence",
size: 5,
});
console.log(numResults, articles[0].title);
// π€ Look up a journalist by ID
const journalist = await perigon.getJournalistById({ id: "123456" });
console.log(journalist.name);
```
> All SDK methods return **typed promises** with full IntelliSense support.
---
## π§βπ» Endpoint snippets
### Articles β search and filter news (`/v1/all`)
**Docs β**
```ts
const { articles } = await perigon.searchArticles({
q: "technology",
size: 5,
});
```
### Articles β date range filter
**Docs β**
```ts
await perigon.searchArticles({
q: "business",
from: "2025-04-01",
to: "2025-04-08",
});
```
### Articles β restrict to a source
**Docs β**
```ts
await perigon.searchArticles({ source: ["nytimes.com"] });
```
### Companies β fetch structured company data (`/v1/companies`)
**Docs β**
```ts
const { results } = await perigon.searchCompanies({
name: "Apple",
size: 5,
});
```
### Journalists β search and detail lookβup (`/v1/journalists`)
**Docs β**
```ts
const { results } = await perigon.searchJournalists1({
name: "Kevin",
size: 1,
});
const journalist = await perigon.getJournalistById({ id: results[0].id });
```
### Stories β discover related article clusters (`/v1/stories`)
**Docs β**
```ts
await perigon.searchStories({ q: "climate change", size: 5 });
```
### Vector search β semantic retrieval (`/v1/vector`)
**Docs β**
```ts
await perigon.vectorSearchArticles({
articleSearchParams: {
prompt: "Latest advancements in artificial intelligence",
size: 5,
},
});
```
### Summarizer β generate an instant summary (`/v1/summarizer`)
**Docs β**
```ts
const { summary } = await perigon.searchSummarizer({
q: "renewable energy",
size: 10,
});
console.log(summary);
```
### Topics β explore taxonomy (`/v1/topics`)
**Docs β**
```ts
await perigon.searchTopics({ size: 10 });
```
| Action | Code Example |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Filter by source | `await perigon.searchArticles({ source: ['nytimes.com'] })` |
| Limit by date range | `await perigon.searchArticles({ q: 'business', from: '2025β04β01', to: '2025β04β08' })` |
| Company lookup | `await perigon.searchCompanies({ name: 'Apple', size: 5 })` |
| Summarize any query | `await perigon.searchSummarizer({ q: 'renewable energy', size: 20 })` |
| Semantic / vector search | `await perigon.vectorSearchArticles({ articleSearchParams: { prompt: 'advancements in AI', size: 5 }})` |
| Retrieve available taxonomic **topics** | `await perigon.searchTopics({ size: 10 })` |
---
## πͺͺ License
MIT Β© Perigon