Cleetus API
Base URL https://api.cleetus.dev. JSON in and out.
Authenticated routes take a Cognito ID or access token as a Bearer
token. Read Cleetus accounts and membership
to sign in, or try a call in the console.
Errors
Errors return a status code and { "message": "…" } written for people.
| Status | Meaning |
|---|---|
400 | Invalid request or webhook signature |
401 | Missing, expired or foreign token. Refresh once, then sign in again. |
404 | No billing account exists yet |
409 | Already a member |
503 | Memberships are not on sale in this environment |
Membership
/v1/membership
Bearer token
Current membership
The signed-in user's membership. Gate member features on active. Only subscriptions in the active Stripe mode count.
curl -s https://api.cleetus.dev/v1/membership \
-H "Authorization: Bearer $CLEETUS_TOKEN"Response · Membership
| Field | Type | Notes |
|---|---|---|
userId | string | Cognito subject. |
email optional | string (email) | |
active | boolean | The only field clients should gate on. |
plan | "member" | "free" | |
source | "subscription" | "complimentary" | null | |
status | string | Stripe subscription status, complimentary or none. |
currentPeriodEnd | integer | null | Unix seconds. |
cancelAtPeriodEnd | boolean | |
hasBillingAccount | boolean | |
mode | "test" | "live" | |
checkedAt | string (date-time) |
/v1/membership/sync
Bearer token
Refresh from Stripe
Re-reads Stripe and returns the membership. Use after checkout returns; webhooks normally keep it current.
curl -s -X POST https://api.cleetus.dev/v1/membership/sync \
-H "Authorization: Bearer $CLEETUS_TOKEN"Response · Membership
| Field | Type | Notes |
|---|---|---|
userId | string | Cognito subject. |
email optional | string (email) | |
active | boolean | The only field clients should gate on. |
plan | "member" | "free" | |
source | "subscription" | "complimentary" | null | |
status | string | Stripe subscription status, complimentary or none. |
currentPeriodEnd | integer | null | Unix seconds. |
cancelAtPeriodEnd | boolean | |
hasBillingAccount | boolean | |
mode | "test" | "live" | |
checkedAt | string (date-time) |
Billing
/plans
Public
Membership plan
Whether memberships are on sale, the monthly price, and the Stripe mode billing runs in.
curl -s https://api.cleetus.dev/plansResponse · Plan
| Field | Type | Notes |
|---|---|---|
available | boolean | |
monthlyCents | integer | null | |
currency | "usd" | |
interval | "month" | |
mode | "test" | "live" |
/v1/membership/checkout
Bearer token
Start checkout
A Stripe Checkout URL for the membership. Returns 409 for existing members and 503 while memberships are closed.
curl -s -X POST https://api.cleetus.dev/v1/membership/checkout \
-H "Authorization: Bearer $CLEETUS_TOKEN"Response · Redirect
| Field | Type | Notes |
|---|---|---|
url | string (uri) |
/v1/membership/portal
Bearer token
Open billing portal
A Stripe billing portal URL for updating payment details, invoices and cancellation.
curl -s -X POST https://api.cleetus.dev/v1/membership/portal \
-H "Authorization: Bearer $CLEETUS_TOKEN"Response · Redirect
| Field | Type | Notes |
|---|---|---|
url | string (uri) |
/stripe/webhook
Public
Stripe events
Stripe-signed subscription events. Payloads are never trusted for access; Stripe's current state is re-read.
curl -s -X POST https://api.cleetus.dev/stripe/webhookResponse · Received
| Field | Type | Notes |
|---|---|---|
received optional | true |
Service
/health
Public
Service health
Liveness for monitors and the status badge. Never cached.
curl -s https://api.cleetus.dev/healthResponse · Health
| Field | Type | Notes |
|---|---|---|
ok | boolean | |
service | "cleetus-api" | |
stage | "dev" | "prod" | |
time | string (date-time) |
/openapi.json
Public
This API description
The OpenAPI 3.1 document for the Cleetus API.
curl -s https://api.cleetus.dev/openapi.jsonResponse · OpenApi
This document.