public-api.md

Renewlet Public API

Renewlet Public API is read-only and scoped to the owner of the token. Create a token in Settings, then send it as a bearer token:

curl -H "Authorization: Bearer rlt_your_token" https://renewlet.example.com/api/public/v1/subscriptions

The API does not accept query parameter tokens, browser session cookies, calendar feed tokens, or public status page tokens.

Machine-readable OpenAPI 3.1 document: docs/public-api.openapi.json.

All JSON success responses use { "ok": true, "data": ... }. Error responses use { "error": { "code", "message", "details?", "requestId?" } }.

Endpoints

GET /api/public/v1/me

Returns the read scope attached to the bearer token. It does not expose the token owner or token hash.

Parameters:

None.

Example:

curl -H "Authorization: Bearer rlt_your_token" "https://renewlet.example.com/api/public/v1/me"

Success response example:

{
  "ok": true,
  "data": {
    "scopes": [
      "read"
    ]
  }
}

GET /api/public/v1/subscriptions

Returns an owner-scoped page of subscriptions ordered by Renewlet's Public API cursor contract.

Parameters:

Name	In	Required	Description
limit	query	no	Page size. The maximum is 100.
cursor	query	no	Opaque cursor returned as data.nextCursor from the previous page.

Example:

curl -H "Authorization: Bearer rlt_your_token" "https://renewlet.example.com/api/public/v1/subscriptions?limit=50"

Success response example:

{
  "ok": true,
  "data": {
    "subscriptions": [
      {
        "id": "sub_01HZY7YQ7EXAMPLE",
        "name": "GitHub",
        "price": "12",
        "currency": "USD",
        "billingCycle": "monthly",
        "category": "developer_tools",
        "status": "active",
        "pinned": false,
        "publicHidden": false,
        "startDate": "2026-01-01",
        "nextBillingDate": "2026-09-01",
        "autoRenew": false,
        "autoCalculateNextBillingDate": true,
        "tags": [
          "dev"
        ],
        "reminderDays": 3,
        "repeatReminderEnabled": false,
        "repeatReminderInterval": "1h",
        "repeatReminderWindow": "72h",
        "extra": {},
        "createdAt": "2026-08-01T00:00:00.000Z",
        "updatedAt": "2026-08-01T00:00:00.000Z"
      }
    ],
    "nextCursor": null,
    "total": 1
  }
}

GET /api/public/v1/subscriptions/{id}

Returns one owner-scoped subscription by id. Foreign or missing ids return the same not found shape.

Parameters:

Name	In	Required	Description
id	path	yes	Subscription id from the list endpoint.

Example:

curl -H "Authorization: Bearer rlt_your_token" "https://renewlet.example.com/api/public/v1/subscriptions/sub_01HZY7YQ7EXAMPLE"

Success response example:

{
  "ok": true,
  "data": {
    "subscription": {
      "id": "sub_01HZY7YQ7EXAMPLE",
      "name": "GitHub",
      "price": "12",
      "currency": "USD",
      "billingCycle": "monthly",
      "category": "developer_tools",
      "status": "active",
      "pinned": false,
      "publicHidden": false,
      "startDate": "2026-01-01",
      "nextBillingDate": "2026-09-01",
      "autoRenew": false,
      "autoCalculateNextBillingDate": true,
      "tags": [
        "dev"
      ],
      "reminderDays": 3,
      "repeatReminderEnabled": false,
      "repeatReminderInterval": "1h",
      "repeatReminderWindow": "72h",
      "extra": {},
      "createdAt": "2026-08-01T00:00:00.000Z",
      "updatedAt": "2026-08-01T00:00:00.000Z"
    }
  }
}

GET /api/public/v1/status

Returns total subscription count and counts by Renewlet status for the token owner.

Parameters:

None.

Example:

curl -H "Authorization: Bearer rlt_your_token" "https://renewlet.example.com/api/public/v1/status"

Success response example:

{
  "ok": true,
  "data": {
    "generatedAt": "2026-08-05T00:00:00.000Z",
    "total": 1,
    "byStatus": {
      "active": 1,
      "trial": 0,
      "expired": 0,
      "paused": 0,
      "cancelled": 0
    }
  }
}

GET /api/public/v1/due

Returns upcoming renewal, trial, or one-time expiry items within the requested day window.

Parameters:

Name	In	Required	Description
days	query	no	Look-ahead window in days. The default is 30 and the maximum is 366.

Example:

curl -H "Authorization: Bearer rlt_your_token" "https://renewlet.example.com/api/public/v1/due?days=30"

Success response example:

{
  "ok": true,
  "data": {
    "days": 30,
    "generatedAt": "2026-08-05T00:00:00.000Z",
    "items": [
      {
        "dueDate": "2026-09-01",
        "dueType": "renewal",
        "subscription": {
          "id": "sub_01HZY7YQ7EXAMPLE",
          "name": "GitHub",
          "price": "12",
          "currency": "USD",
          "billingCycle": "monthly",
          "category": "developer_tools",
          "status": "active",
          "pinned": false,
          "publicHidden": false,
          "startDate": "2026-01-01",
          "nextBillingDate": "2026-09-01",
          "autoRenew": false,
          "autoCalculateNextBillingDate": true,
          "tags": [
            "dev"
          ],
          "reminderDays": 3,
          "repeatReminderEnabled": false,
          "repeatReminderInterval": "1h",
          "repeatReminderWindow": "72h",
          "extra": {},
          "createdAt": "2026-08-01T00:00:00.000Z",
          "updatedAt": "2026-08-01T00:00:00.000Z"
        }
      }
    ]
  }
}