> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sub.jerrylu.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Public API overview

> Use Developer API keys to automate subscription lifecycle, analytics, and audit access through the v1 public API.

# 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

```text theme={null}
https://your-site.example/api/v1
```

Main endpoint groups live under:

```text theme={null}
/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:

| Artifact                             | Use it for                                                           |
| ------------------------------------ | -------------------------------------------------------------------- |
| [OpenAPI schema](/api/openapi.yaml)  | Endpoint schemas, examples, auth, and `x-ai` task metadata           |
| [AI tool schema](/api/ai-tools.json) | Function/tool definitions with risk levels and confirmation guidance |
| [AI tool usage guide](/api/ai-tools) | 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:

```bash theme={null}
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](/api-reference) for endpoint schemas, parameters, and response examples.