REST API
Billing
Usage tracking, quotas, and subscription management
Check Your Usage
curl -H "Authorization: Bearer sk_live_..." \
http://localhost:8000/api/v1/billing/usage/currentReturns usage stats for the current billing period.
Upgrade Your Plan
curl -X POST -H "Authorization: Bearer sk_live_..." \
http://localhost:8000/api/v1/billing/checkoutReturns a Stripe checkout URL to complete the upgrade.
Check Subscription Status
curl -H "Authorization: Bearer sk_live_..." \
http://localhost:8000/api/v1/billing/subscriptions/{subscription_id}Report Usage
curl -X POST http://localhost:8000/api/v1/billing/usage/report \
-H "Authorization: Bearer sk_live_..." \
-H "Idempotency-Key: unique-request-id"The Idempotency-Key header prevents duplicate charges. Each call reports one unit of usage.
Rate Limits & Quotas
- Requests are rate-limited per client
- Each subscription tier has a daily quota:
| Tier | Daily requests |
|---|---|
| Free | 100 |
| Pro | 10,000 |
- When you exceed your daily quota, the API returns
402with aRetry-Afterheader indicating when the quota resets (next day) - Rate-limited requests return
429- wait and retry