API Overview
The Windback API lets you manage churn events, generate recovery emails, track customer behavior, and access analytics programmatically.
Base URL
https://api.windbackai.com/api/v1
Authentication
Windback supports two authentication methods:
JWT Bearer Token
Used by the dashboard and web app. Obtained via login or OAuth.Authorization: Bearer eyJhbGciOi...
API Key
Used for server-side SDK calls and API access. Pass via header.X-API-Key: sk_live_abc123...
Never expose your secret key (sk_) in client-side code. Use the public key (pub_) for widgets and webhooks.
Endpoints
Authentication
| Method | Endpoint | Description |
|---|
POST | /auth/register | Register a new account |
POST | /auth/login | Login and receive JWT |
POST | /auth/google | OAuth login with Google |
GET | /auth/me | Get current user |
POST | /auth/forgot-password | Request password reset |
POST | /auth/reset-password | Reset password with token |
Projects
| Method | Endpoint | Description |
|---|
POST | /projects | Create a new project |
GET | /projects | List all projects |
GET | /projects/:slug | Get project by slug |
PATCH | /projects/:slug | Update project settings |
POST | /projects/:slug/rotate-keys | Rotate API keys |
Churn Events
| Method | Endpoint | Description |
|---|
POST | /projects/:slug/churn-events | Create a churn event |
GET | /projects/:slug/churn-events | List churn events (paginated) |
GET | /projects/:slug/churn-events/:id | Get a single churn event |
POST | /projects/:slug/churn-events/:id/recovered | Mark event as recovered |
PATCH | /projects/:slug/churn-events/:id/cancel-reason | Update cancel reason |
Recovery & Email Variants
| Method | Endpoint | Description |
|---|
POST | /projects/:slug/churn-events/:id/generate | Generate 9 AI recovery variants |
POST | /projects/:slug/churn-events/:id/variants/:vid/send | Send a variant email |
PATCH | /projects/:slug/churn-events/:id/variants/:vid | Update a variant before sending |
GET | /projects/:slug/churn-events/:id/variants | List all variants for an event |
Stats & Analytics
| Method | Endpoint | Description |
|---|
GET | /projects/:slug/stats | Get project churn statistics |
GET | /projects/:slug/cohorts | Get cohort analysis data |
GET | /projects/:slug/forecasting | Get revenue forecasting data |
Event Tracking
| Method | Endpoint | Description |
|---|
POST | /track | Track customer behavior events |
Cancel Flow
| Method | Endpoint | Description |
|---|
POST | /cancel-flow/reasons | Submit cancel reason from widget |
GET | /cancel-flow/config/:publicKey | Get cancel flow configuration |
Webhooks
| Method | Endpoint | Description |
|---|
POST | /webhooks/stripe/:publicKey | Receive Stripe webhook events |
POST | /webhooks/razorpay/:publicKey | Receive Razorpay webhook events |
POST | /webhooks/custom/:publicKey | Receive custom webhook events |
Team & Invitations
| Method | Endpoint | Description |
|---|
POST | /projects/:slug/invitations | Invite a team member |
GET | /projects/:slug/members | List project members |
DELETE | /projects/:slug/members/:id | Remove a team member |
POST | /invitations/:token/accept | Accept an invitation |
Success Response
{
"data": { ... },
"meta": {
"page": 1,
"per_page": 20,
"total": 42
}
}
Error Response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "customer_email is required",
"details": [
{
"field": "customer_email",
"message": "This field is required"
}
]
}
}
| Parameter | Type | Default | Description |
|---|
page | integer | 1 | Page number |
per_page | integer | 20 | Items per page (max 100) |
sort | string | created_at | Sort field |
order | string | desc | Sort order: asc or desc |
curl "https://api.windbackai.com/api/v1/projects/my-project/churn-events?page=2&per_page=50" \
-H "X-API-Key: sk_live_abc123..."
Error Handling
| HTTP Status | Error Code | Description |
|---|
400 | VALIDATION_ERROR | Invalid request body or parameters |
401 | UNAUTHORIZED | Missing or invalid authentication |
403 | FORBIDDEN | Insufficient permissions |
404 | NOT_FOUND | Resource not found |
409 | CONFLICT | Duplicate resource |
429 | RATE_LIMITED | Too many requests |
500 | INTERNAL_ERROR | Server error |
Rate Limits
| Endpoint Group | Limit |
|---|
| Auth (login, register) | 5 req/s, burst 10 |
| Cancel flow | 10 req/15s per key |
| Event tracking | Plan-based per key |
| General API | 10 req/s, burst 30 |
Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in all responses.
