> ## Documentation Index
> Fetch the complete documentation index at: https://steadyrenew.com/docs/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/notification-settings
/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` is returned on records and accepted as a list filter, but is not writable through the public API.
* Notification settings expose only `enabled` and `daysBefore` for writes; Bark URL, test push, timeZone, and locale stay web-managed.
* 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](/docs/api/openapi.yaml) | Endpoint schemas, examples, auth, and `x-ai` task metadata |
| [AI tool schema](/docs/api/ai-tools.json) | Function/tool definitions with risk levels and confirmation guidance |
| [AI tool usage guide](/docs/api/ai-tools) | Prompting, operation choice, and safety policy |

## Default plan limits

| Plan | Active keys | Requests |
| - | -: | -: |
| Free | 5 | 60 requests per account per minute |
| Premium | 5 | 60 requests per account per minute |

You can override defaults with server-only environment variables:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.