# Perigon Sdks

> Best practices for using the official Perigon SDKs (TypeScript, Python, Go). Use this skill when installing, configuring, or writing code with any Perigon SDK to search news, track stories, summarize content, perform vector search, query Wikipedia, or look up people, companies, journalists, and sources.

- **Type:** Skill
- **Install:** `agentstack add skill-goperigon-skills-perigon-sdks`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [goperigon](https://agentstack.voostack.com/s/goperigon)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [goperigon](https://github.com/goperigon)
- **Source:** https://github.com/goperigon/skills/tree/main/skills/perigon-sdks

## Install

```sh
agentstack add skill-goperigon-skills-perigon-sdks
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Perigon SDKs Best Practices

Guide for using the official Perigon SDKs to integrate the Perigon News Intelligence API into TypeScript/Node.js, Python, and Go applications.

## When to Apply

Reference these guidelines when:
- Installing or setting up a Perigon SDK in a new or existing project
- Initializing the Perigon client and configuring authentication
- Calling any Perigon API endpoint through an SDK (articles, stories, vector search, summarizer, Wikipedia, entities)
- Handling errors, retries, or rate limits from SDK calls
- Choosing which SDK to use for a given project or runtime
- Writing async code with the Python SDK or context-based code with the Go SDK
- Constructing typed request parameters or parsing typed responses

## SDK Selection Guide

```
TypeScript/JavaScript project?  → @goperigon/perigon-ts
Python project?                 → perigon (PyPI)
Go project?                     → github.com/goperigon/perigon-go-sdk/v2
```

All three SDKs cover the same API surface. Choose based on your project language.

## SDK Comparison

| | TypeScript | Python | Go |
|---|---|---|---|
| **Package** | `@goperigon/perigon-ts` | `perigon` | `github.com/goperigon/perigon-go-sdk/v2` |
| **Install** | `npm install @goperigon/perigon-ts` | `pip install perigon` | `go get github.com/goperigon/perigon-go-sdk/v2` |
| **Client init** | `new V1Api(new Configuration({apiKey}))` | `V1Api(ApiClient(api_key=...))` | `perigon.NewClient(option.WithAPIKey(...))` |
| **Method style** | `perigon.searchArticles({...})` | `api.search_articles(...)` | `client.All.List(ctx, params)` |
| **Async** | Native Promises | `_async` suffix methods | Context-based |
| **Type system** | Full TS types | Pydantic models, PEP 561 | Strongly-typed with `param.Opt[T]` |
| **Error type** | `ResponseError` | `ApiException` | `*perigon.Error` |
| **Retries** | Manual | Manual | Built-in (default 2) |

## Authentication

All SDKs read the API key from the `PERIGON_API_KEY` environment variable by default. You can also pass it explicitly:

**TypeScript:**
```ts
import { Configuration, V1Api } from "@goperigon/perigon-ts";
const perigon = new V1Api(new Configuration({ apiKey: process.env.PERIGON_API_KEY }));
```

**Python:**
```python
from perigon import V1Api, ApiClient
api = V1Api(ApiClient(api_key=os.environ["PERIGON_API_KEY"]))
```

**Go:**
```go
client := perigon.NewClient() // reads PERIGON_API_KEY env var
// or explicitly:
client := perigon.NewClient(option.WithAPIKey("your-key"))
```

## Endpoint-to-Method Mapping

| API Endpoint | TypeScript | Python | Go |
|---|---|---|---|
| `GET /v1/articles/all` | `searchArticles()` | `search_articles()` | `client.All.List()` |
| `GET /v1/stories/all` | `searchStories()` | `search_stories()` | `client.Stories.List()` |
| `GET /v1/stories/history` | `getStoryHistory()` | `get_story_history()` | — |
| `POST /v1/summarize` | `searchSummarizer()` | `search_summarizer()` | `client.Summarize.New()` |
| `POST /v1/vector/news/all` | `vectorSearchArticles()` | `vector_search_articles()` | `client.Vector.News.Search()` |
| `GET /v1/wikipedia/all` | `searchWikipedia()` | `search_wikipedia()` | `client.Wikipedia.Search()` |
| `POST /v1/vector/wikipedia/all` | `vectorSearchWikipedia()` | `vector_search_wikipedia()` | `client.Wikipedia.VectorSearch()` |
| `GET /v1/companies/all` | `searchCompanies()` | `search_companies()` | `client.Companies.List()` |
| `GET /v1/people/all` | `searchPeople()` | `search_people()` | `client.People.List()` |
| `GET /v1/journalists/all` | `searchJournalists()` | `search_journalists()` | `client.Journalists.List()` |
| `GET /v1/journalists/{id}` | `getJournalistById()` | `get_journalist_by_id()` | `client.Journalists.Get()` |
| `GET /v1/sources/all` | `searchSources()` | `search_sources()` | `client.Sources.List()` |
| `GET /v1/topics/all` | `searchTopics()` | `search_topics()` | `client.Topics.List()` |

## Common Patterns

### Search Articles

**TypeScript:**
```ts
const { articles } = await perigon.searchArticles({ q: "AI", size: 10, sortBy: "date" });
```

**Python:**
```python
result = api.search_articles(q="AI", size=10, sort_by="date")
```

**Go:**
```go
result, err := client.All.List(ctx, perigon.AllListParams{
    Q:      perigon.String("AI"),
    Size:   perigon.Int(10),
    SortBy: perigon.AllEndpointSortByDate,
})
```

### Story History

**TypeScript:**
```ts
const { results } = await perigon.getStoryHistory({
  clusterId: ["911860d569ca464698c0beec0697f694"],
  changelogExists: true,
  size: 10,
});
```

**Python:**
```python
result = api.get_story_history(
    cluster_id=["911860d569ca464698c0beec0697f694"],
    changelog_exists=True,
    size=10,
)
```

**Go:** Not yet available in the Go SDK. Use the REST API directly or the TypeScript/Python SDK.

### Vector Search

**TypeScript:**
```ts
const results = await perigon.vectorSearchArticles({
    articleSearchParams: { prompt: "impact of AI on healthcare", size: 5 },
});
```

**Python:**
```python
from perigon.models import ArticleSearchParams
results = api.vector_search_articles(
    article_search_params=ArticleSearchParams(prompt="impact of AI on healthcare", size=5)
)
```

**Go:**
```go
results, err := client.Vector.News.Search(ctx, perigon.VectorNewsSearchParams{
    Prompt: "impact of AI on healthcare",
    Size:   perigon.Int(5),
})
```

### Error Handling

**TypeScript:**
```ts
try {
    const result = await perigon.searchArticles({ q: "test" });
} catch (error) {
    if (error.status === 429) console.error("Rate limited");
}
```

**Python:**
```python
from perigon.exceptions import ApiException
try:
    result = api.search_articles(q="test")
except ApiException as e:
    print(f"HTTP {e.status}: {e.body}")
```

**Go:**
```go
result, err := client.All.List(ctx, perigon.AllListParams{Q: perigon.String("test")})
if err != nil {
    var apierr *perigon.Error
    if errors.As(err, &apierr) {
        fmt.Printf("HTTP %d\n", apierr.StatusCode)
    }
}
```

## SDK-Specific Gotchas

1. **Python `from` keyword**: Use `var_from` instead of `from` for date filtering (Python reserved word).
2. **Python POST body params**: Vector search and summarization require model objects (`ArticleSearchParams`, `SummaryBody`, `WikipediaSearchParams`).
3. **Go optional fields**: Use `perigon.String()`, `perigon.Int()`, `perigon.Float()`, `perigon.Time()` constructors for optional parameters.
4. **Go retries**: Built-in exponential backoff (2 retries by default). Override with `option.WithMaxRetries()`.
5. **TypeScript middleware**: Use `Configuration({ middleware: [...] })` for request/response hooks.

## How to Use References

Read individual reference files for detailed SDK-specific documentation:

```
references/typescript-sdk.md  — Full @goperigon/perigon-ts reference
references/python-sdk.md      — Full perigon Python SDK reference
references/go-sdk.md          — Full perigon-go-sdk/v2 reference
```

Each reference contains:
- Installation and setup instructions
- Complete method reference with all parameters
- Code examples for every endpoint
- Error handling patterns
- Advanced features (middleware, async, retries, pagination)

## External References

- [TypeScript SDK — GitHub](https://github.com/goperigon/perigon-ts)
- [Python SDK — GitHub](https://github.com/goperigon/perigon-python)
- [Go SDK — GitHub](https://github.com/goperigon/perigon-go-sdk)
- [Perigon API Documentation](https://docs.perigon.io)
- [Perigon API Reference](https://www.perigon.io/reference)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [goperigon](https://github.com/goperigon)
- **Source:** [goperigon/skills](https://github.com/goperigon/skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-goperigon-skills-perigon-sdks
- Seller: https://agentstack.voostack.com/s/goperigon
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.