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

Authentication

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

TypeScript:

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

Python:

from perigon import V1Api, ApiClient
api = V1Api(ApiClient(api_key=os.environ["PERIGON_API_KEY"]))

Go:

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

Endpoint-to-Method Mapping

Common Patterns

Search Articles

TypeScript:

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

Python:

result = api.search_articles(q="AI", size=10, sort_by="date")

Go:

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

Vector Search

TypeScript:

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

Python:

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

Go:

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

Error Handling

TypeScript:

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

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:

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
• Python SDK — GitHub
• Go SDK — GitHub
• Perigon API Documentation
• Perigon API Reference