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 the authoritative renewal date; monthly schedules preserve their original calendar-day anchor.
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:

Artifact	Use it for
OpenAPI schema	Endpoint schemas, examples, auth, and `x-ai` task metadata
AI tool schema	Function/tool definitions with risk levels and confirmation guidance
AI tool usage guide	Prompting, operation choice, and safety policy

Default plan limits

Plan	Active keys	Requests
Free	1	60 requests per user per hour
Premium	5	1000 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

Method	Path	Description
`GET`	`/api/v1/subscriptions`	List subscriptions
`GET`	`/api/v1/subscriptions/{id}`	Get one subscription
`POST`	`/api/v1/subscriptions`	Create a subscription
`PATCH`	`/api/v1/subscriptions/{id}`	Update writable fields
`DELETE`	`/api/v1/subscriptions/{id}`	Delete a subscription
`GET`	`/api/v1/analytics/summary`	Spend summary by currency/category and upcoming renewals
`GET`	`/api/v1/analytics/duplicates`	Duplicate subscription candidates
`GET`	`/api/v1/analytics/optimizations`	Optimization candidates without invented savings
`GET`	`/api/v1/audit`	Public API write audit log

API reference

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

​Public API overview

​Base path

​Design choices

​AI-ready artifacts

​Default plan limits

​Endpoints

​API reference