The Renew Reminder API

Authentication

Send your key as a bearer token. Keys look like rrk_live_... and are shown once at creation. We store only a hash, so a lost key cannot be recovered. To replace a key that is lost or exposed, revoke it in the web app and create a new one.

Authorization: Bearer rrk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Call the API from your own server, never from a web page. A key is a secret that belongs in a server's environment, and the API grants no browser origin CORS access, so a request made from front-end code fails in the browser.

Endpoints

Create a record

curl -X POST https://api.renewreminder.com/api/v1/records \
  -H "Authorization: Bearer $RR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Figma",
    "amount": 45,
    "currency": "USD",
    "billingCycle": "monthly",
    "nextBillingDate": "2026-09-01",
    "category": "Design"
  }'

Records created this way are stamped source: "api" by the server and land in the key's workspace. You cannot set either from the request body. A new record answers 201; if an identical record already exists, you get that one back with 200 and "deduped": true instead of a second copy.

Check a key

GET /me describes the key you sent: the workspace it belongs to, the plan that entitles it (business_starter or business), and the key's own details. It returns no personal data about the person who created the key, only their user id.

{
  "success": true,
  "workspace": { "id": "8f2c...", "name": "Acme Inc.", "baseCurrency": "USD" },
  "plan": "business_starter",
  "key": {
    "prefix": "rrk_live_x7Q",
    "name": "Finance sync",
    "environment": "live",
    "scopes": ["records:read", "categories:read", "insights:read", "profile:read"],
    "createdBy": "3a91..."
  }
}

The record object

One shape covers subscriptions, bills and investments; the type field tells them apart. Absent values are null, never missing.

{
  "id": "665f1c...",
  "type": "subscription",
  "name": "Figma",
  "description": null,
  "merchant": "Figma Inc.",
  "amount": 45,
  "currency": "USD",
  "originalAmount": null,
  "originalCurrency": null,
  "originalCurrencySymbol": null,
  "billingCycle": "monthly",
  "nextBillingDate": "2026-09-01T00:00:00.000Z",
  "lastBillingDate": "2026-08-01T00:00:00.000Z",
  "trialEndDate": null,
  "billingPhase": "paid",
  "category": "Design",
  "tags": [],
  "notes": null,
  "splitCount": 1,
  "isActive": true,
  "autoRenew": true,
  "source": "api",

  "workspaceId": "8f2c...",
  "ownerUserId": "3a91...",
  "department": "Design",
  "noticePeriodDays": 60,
  "contractEndDate": "2026-12-31T00:00:00.000Z",
  "autoRenews": true,
  "endsOn": null,
  "renewalDecision": {
    "status": "renew",
    "decidedBy": "3a91...",
    "decidedAt": "2026-08-10T11:20:00.000Z",
    "note": "Renegotiated to 40/seat"
  },
  "ownerTag": {
    "name": "Sarah Lee",
    "email": "sarah@example.com",
    "notify": true,
    "optedOutAt": null
  },
  "vendorContacts": [],

  "createdAt": "2026-08-01T09:12:44.000Z",
  "updatedAt": "2026-08-13T07:03:10.000Z"
}

Writable fields. A PATCH accepts name, description, merchant, amount, currency, billingCycle, nextBillingDate, lastBillingDate, trialEndDate, category, tags, notes, splitCount, isActive, autoRenew, ownerUserId, department, noticePeriodDays, contractEndDate, autoRenews, plus renewalDecision with a status and a note; the server stamps who decided and when. A POST accepts the same fields except renewalDecision, plus recordType, billingPhase, icon, color, referenceNumber, isVariableAmount, ownerTag, vendorContacts.

Any other field in the body is ignored, not rejected, and the response lists it in ignoredFields, on a POST as on a PATCH. Check that list: it is how a typo shows up. A PATCH with no field it accepts answers 400 INVALID_REQUEST.

Filtering and pagination

GET /records accepts type, category, active, search, billingCycle, page, limit. type, category, billingCycle and search each take a single value; repeating one answers 400 INVALID_REQUEST. Pages are 25 records by default and 100 at most, and page is capped at 1000: a higher number returns page 1000.

curl "https://api.renewreminder.com/api/v1/records?active=true&billingCycle=yearly&limit=50" \
  -H "Authorization: Bearer $RR_API_KEY"

The records come back in records, with a pagination block:

{
  "success": true,
  "records": [ ... ],
  "pagination": { "page": 1, "limit": 50, "total": 128, "hasMore": true }
}

GET /records/upcoming is not paginated. It takes days (30 by default, 1 to 365) and returns the active records billing within that window, soonest first, at most 500 of them. When more qualify, you get the 500 soonest and the response carries "hasMore": true; page through GET /records for the full list.

{
  "success": true,
  "windowDays": 30,
  "records": [ ... ],
  "hasMore": true
}

Scopes

Each key carries a set of scopes fixed when it is created. New keys are read-only unless you choose otherwise: in the web app, Read only grants records:read, categories:read, insights:read, profile:read, and Read and write adds records:write, categories:write. Choose read and write only for a system that needs to change records.

Workspace keys

Every API key belongs to one workspace on Business Starter or Business, including the 14-day trial. Keys are created in the web app: open the workspace, then Settings → API keys. The workspace's owner and its Admins can create keys, and see and revoke every key in the workspace, whoever created it. The key is shown once, when you create it.

A key reaches its own workspace and nothing else. It reads and writes that workspace's records and categories, never another workspace's and never anyone's personal subscriptions. Records it creates are tagged to the workspace automatically — you cannot set workspaceId from a request body.

Quota and key allowances follow the workspace's plan, not the plan of whoever created the key, and the key allowance is a shared pool across the company rather than per person.

Rate limits and quotas

Two limits apply: a monthly call quota and a per-minute burst. Both are set by the workspace's plan, and both are counted per key, so each key has the full allowance below. The month is the calendar month in UTC. The Keys column is the most live keys one workspace can hold, shared by all its Admins. During the 14-day trial, the limits are those of the plan being trialled.

API access is part of the Business plans; Premium and the free plan do not include it. Every response tells you where you stand on the monthly quota, so you never have to guess:

X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 99412
X-RateLimit-Period: 2026-08

Going over the burst answers 429 RATE_LIMITED, and a call refused that way does not count against the month. Running out of the monthly quota answers 429 API_QUOTA_EXCEEDED until the next month begins.

Errors

Failures return a JSON body with a stable code. Branch on the code, not the message — messages get reworded, codes do not.

A record id that matches nothing in the key's workspace answers 404 NOT_FOUND. If the API itself is switched off, every path answers 404 with no code at all; API_UNAVAILABLE only means a key could not be checked for a moment.

Versioning

The version is in the path, from the first release. Within v1 we only add: new endpoints, new optional parameters, new fields on a response. Removing a field, renaming one, or changing what a value means would be v2. Write clients that ignore fields they do not recognise.

Known limitations

Stated plainly, because you would find them anyway:

• No sandbox

  Every key reads and writes the workspace's real records; there is no separate test environment. Do not point a test suite at a workspace you rely on.

• No outbound webhooks yet

  Nothing calls you when a renewal approaches; you poll /records/upcoming instead. Signed webhooks are planned, and are what a Slack or ticketing integration should eventually be built on.

• No bulk endpoint or idempotency key

  Import one record per request for now. The server does de-duplicate records that look identical, but that is a safety net rather than a guarantee you can build a retry loop on.