Developer Documentation

Integration Guide

Get started with ThriftyAI in minutes. Reduce costs by 80% and speed up responses by 10x.

Security Best Practices

Critical security guidelines to protect your API keys

Never expose keys in client-side code

Always use server-side environments

Store in environment variables

Use .env files, never commit them

Add .env to .gitignore

Prevent accidental Git exposure

Your keys, your control

We never store provider keys

Quick Start

Choose your AI provider and get the integration code

import requests

response = requests.post(
    "https://thriftyai.app/api/gateway",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_THRIFTYAI_API_KEY",
        "x-provider-key": "YOUR_OPENAI_API_KEY",
        "x-provider": "openai",
        # Optional: Track per-user for high-traffic apps
        # "x-end-user-id": "user_12345",
        # Optional: Add fallback support
        # "x-fallback-provider": "google",
        # "x-fallback-model": "gemini-1.5-flash",
        # "x-fallback-key": "YOUR_GEMINI_API_KEY",
        # Optional: Set cache TTL (seconds)
        # "x-cache-ttl": "300",
    },
    json={
        "model": "gpt-3.5-turbo",
        "messages": [
            {"role": "user", "content": "What is the capital of France?"}
        ]
    }
)

result = response.json()
print(result)

Installation:

pip install openai

Automatic Fallback

Prevent downtime! If primary provider fails, automatically switch to backup.

x-fallback-providerBackup provider name

x-fallback-modelModel to use on fallback

x-fallback-keyFallback provider API key

Canary Caching

Control cache freshness with zero latency. Get instant stale responses while fresh data fetches in background.

x-cache-ttlCache TTL in seconds (e.g., 300)

Header overrides dashboard default setting

Cache Management

Purge cache entries when you need fresh responses

When to purge cache:

After updating your app's training data or knowledge base
When you want to force fresh responses for specific prompts
During development and testing phases
When debugging cache behavior

Remove a specific cache entry using its log ID from your dashboard.

import requests

response = requests.post(
    "https://thriftyai.app/api/cache/purge",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
    },
    json={"log_id": "LOG_ID_FROM_DASHBOARD"}
)

result = response.json()
print(result)

Webhooks Integration

Receive real-time notifications for requests, cache hits, errors, and more

Available Events:

request.completed

request.failed

cache.hit

cache.miss

cache.stale

error.quota

error.rate_limit

error.provider

fallback.triggered

Create a webhook to receive notifications. Save the returned secret for signature verification.

import requests

response = requests.post(
    "https://thriftyai.app/api/webhooks",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
    },
    json={
        "url": "https://your-app.com/webhooks/thriftyai",
        "events": ["request.completed", "cache.hit", "cache.miss"],
        "description": "My analytics webhook"
    }
)

result = response.json()
print(f"Webhook ID: {result['id']}")
print(f"Secret: {result['secret']}")

Webhook Features:

HMAC-SHA256 signature verification for security
Automatic retry with exponential backoff (max 5 attempts)
Delivery tracking and debugging in dashboard
Test webhook functionality before going live
9 different event types for comprehensive monitoring

Why ThriftyAI?

50-80% Cost Reduction

Cache hits are free, pay only for misses

10x Faster Responses

~100ms cached vs 1-2s provider latency

Cross-Provider Cache

Similar prompts hit same cache across all providers

Your Keys, Your Control

We never store provider keys, you keep full control