SDK / Client Libraries

Official JavaScript/TypeScript SDK

Use our official SDK for the easiest integration. Fully typed, production-ready, and maintained by the Proofio team.

Fully typed with TypeScript
Automatic retry logic
Rate limit handling
npm install proofio-sdk

Quick Start

import { Proofio } from 'proofio-sdk';

const proofio = new Proofio({ apiKey: 'your-api-key' });

// List reviews
const reviews = await proofio.reviews.list();

// Get insights summary
const summary = await proofio.insights.summary();

// Get widget data
const widget = await proofio.widget.get();

Examples

List Reviews with Filters

const reviews = await proofio.reviews.list({
  limit: 50,
  minRating: 4,
  sentiment: 'positive',
  language: 'de',
  sourceId: 'source-id-here',
});

Get Insights Summary

const summary = await proofio.insights.summary();

console.log(`Total Reviews: ${summary.totalReviews}`);
console.log(`Average Rating: ${summary.averageRating}`);
console.log(`Rating Distribution:`, summary.ratingDistribution);
console.log(`Sentiment:`, summary.sentimentDistribution);

// AI Summary (if available for paid plans)
if (summary.aiSummary) {
  console.log(`AI Summary: ${summary.aiSummary.summary}`);
}

Error Handling

import { Proofio, ProofioError } from 'proofio-sdk';

try {
  const reviews = await proofio.reviews.list();
} catch (error) {
  if (error instanceof ProofioError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status: ${error.status}`);
    console.error(`Code: ${error.code}`);
    
    // Rate limit handling
    if (error.status === 429) {
      console.error(`Rate limit exceeded. Retry after: ${error.retryAfter} seconds`);
    }
    
    // Check if retryable
    if (error.isRetryable()) {
      // Implement retry logic
    }
  }
}

Pagination

// The API returns up to 100 reviews per request (max limit).
// Use the limit parameter to control how many reviews to fetch.
const reviews = await proofio.reviews.list({ limit: 100 });
console.log(`Fetched ${reviews.length} reviews`);

Configuration

const proofio = new Proofio({
  apiKey: 'your-api-key',
  baseURL: 'https://api.proofio.app', // Optional, default: https://api.proofio.app
  timeout: 30000, // Optional, default: 30000ms (30 seconds)
  maxRetries: 3, // Optional, default: 3
  retryDelay: 1000, // Optional, default: 1000ms (1 second)
});

API Reference

Reviews

// List reviews with optional filters
await proofio.reviews.list(options?: ReviewFilterOptions): Promise<Review[]>

Aggregations

// Get aggregated stats (totalReviews, averageRating, sentiment, sources, aiSummary)
await proofio.aggregations.get(): Promise<Aggregations>

Clusters

// Get review clusters with keyword groupings
await proofio.clusters.list(): Promise<Cluster[]>

Insights

// Get AI-powered intelligence (trust score, risk, emotions, topics)
await proofio.insights.get(): Promise<InsightsResponse>

// Convenience alias for aggregations.get()
await proofio.insights.summary(): Promise<Aggregations>

Widget

// Get widget data (stats + settings)
await proofio.widget.get(): Promise<WidgetData>

Manual HTTP Client Examples

If you prefer to use the API directly without the SDK, here are examples for common HTTP clients:

JavaScript/TypeScript (Fetch API)

const headers = {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const reviews = await fetch("https://api.proofio.app/api/v1/public/reviews", {
  headers,
}).then((r) => r.json());

Python

import requests

headers = {'x-api-key': 'YOUR_API_KEY'}
reviews = requests.get('https://api.proofio.app/api/v1/public/reviews', headers=headers).json()

cURL

curl https://api.proofio.app/api/v1/public/reviews \
  -H "x-api-key: YOUR_API_KEY"

Need Help?

Check out the full SDK documentation on npm or visit our GitHub repository.