Skip to main content

​
Public API overview

The v1 public API exposes subscription lifecycle management, analytics, and audit access through Developer API keys. It is designed for scripts, agents, automation tools, and third-party integrations.

​
Base path

https://your-site.example/api/v1
Main endpoint groups live under: 
/api/v1/subscriptions
/api/v1/analytics
/api/v1/audit

​
Design choices

  • API responses are JSON.
  • Request and response field names use camelCase.
  • Database-managed fields are read-only.
  • The API key owner determines the user scope.
  • Every subscription query is filtered by the authenticated API key owner.
  • nextPaymentDate is calculated by the server from billing period fields.
  • status supports soft lifecycle changes: active, paused, and cancelled.
  • Analytics endpoints report totals per currency and never convert across currencies.
  • Audit endpoints expose write history for public API create, update, and delete operations.
  • Write operations return AI-readable validation errors when a specific field can be corrected.

​
AI-ready artifacts

Use these files when connecting an AI assistant or agent framework:
ArtifactUse it for
OpenAPI schemaEndpoint schemas, examples, auth, and x-ai task metadata
AI tool schemaFunction/tool definitions with risk levels and confirmation guidance
AI tool usage guidePrompting, operation choice, and safety policy

​
Default plan limits

PlanActive keysRequests
Free160 requests per user per hour
Premium51000 requests per user per hour
You can override defaults with server-only environment variables: 
API_FREE_RATE_LIMIT_PER_HOUR=60
API_PREMIUM_RATE_LIMIT_PER_HOUR=1000
API_FREE_ACTIVE_KEYS=1
API_PREMIUM_ACTIVE_KEYS=5
API_FAILED_AUTH_RATE_LIMIT_PER_HOUR=300
API_RATE_LIMIT_RETENTION_HOURS=48

​
Endpoints

MethodPathDescription
GET/api/v1/subscriptionsList subscriptions
GET/api/v1/subscriptions/{id}Get one subscription
POST/api/v1/subscriptionsCreate a subscription
PATCH/api/v1/subscriptions/{id}Update writable fields
DELETE/api/v1/subscriptions/{id}Delete a subscription
GET/api/v1/analytics/summarySpend summary by currency/category and upcoming renewals
GET/api/v1/analytics/duplicatesDuplicate subscription candidates
GET/api/v1/analytics/optimizationsOptimization candidates without invented savings
GET/api/v1/auditPublic API write audit log

​
API reference

Use the generated API Reference for endpoint schemas, parameters, and response examples.