RevHold is an AI-powered business assistant and churn detection tool that helps SaaS founders prevent customer churn by analyzing real usage data and identifying at-risk customers before they leave.

How does the churn detection tool work?

Our AI analyzes customer usage patterns, engagement metrics, and behavioral signals to predict churn risk. You can ask questions in plain English and get actionable insights about which customers are at risk and why.

Can RevHold help identify upsell opportunities?

Yes, RevHold identifies customers who are ready for upgrades based on their usage patterns, feature adoption, and engagement levels, helping you maximize revenue retention.

API Reference

The RevHold REST API provides programmatic access to send usage events and query AI insights. All endpoints require API key authentication and return JSON responses.

Base URL

https://www.revhold.io/api

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Complete Endpoint URLs

All endpoints in this documentation are relative to the base URL. For example, /usage becomes https://www.revhold.io/api/usage

Authentication

Authenticate requests by including your API key in the Authorization header using the Bearer authentication scheme.

Header Format

Authorization: Bearer YOUR_API_KEY

Keep your API key secure

Never expose your API key in client-side code or version control. Always make API calls from your backend server.

Versioning

The current API version is v1. We maintain backward compatibility and will announce any breaking changes well in advance.

Current version: v1 (implicit in all endpoints)
Stability: Production-ready

Endpoints

POST/usage

Send a usage event to track user activity. Events are processed in real-time and become available for AI analysis immediately.

Request Schema

Field	Type	Required	Description
userId	string	Yes	Unique identifier for the user (max 255 chars)
eventName	string	Yes	Name of the event (max 100 chars)
eventValue	number	No	Numeric value (default: 1, range: -999999 to 999999)
timestamp	string	Yes	ISO 8601 format (e.g., 2025-01-02T14:30:00Z)

Response Schema (200 OK)

Field	Type	Description
success	boolean	Always true for successful requests
message	string	Human-readable success message
eventId	string	Unique identifier for the recorded event

Example Requests

curl -X POST https://www.revhold.io/api/usage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_abc123",
    "eventName": "feature_used",
    "eventValue": 1,
    "timestamp": "2025-01-02T14:30:00Z"
  }'

Example Response

200 OK

{
  "success": true,
  "message": "Usage event recorded",
  "eventId": "evt_xyz789"
}

POST/ai

Ask a question about your usage data. The AI will analyze your events and return actionable insights in plain English. Limited to 20 questions on trial accounts.

Request Schema

Field	Type	Required	Description
question	string	Yes	Question about your usage data (max 500 chars)

Response Schema (200 OK)

Field	Type	Description
answer	string	AI-generated insight in plain English
confidence	string	Confidence level: "high", "medium", or "low"
dataPoints	number	Number of events analyzed to generate the answer

Example Requests

curl -X POST https://www.revhold.io/api/ai \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Which users are most engaged this week?"
  }'

Example Response

200 OK

{
  "answer": "Based on your usage data, 5 users are highly engaged this week: user_123 (47 events), user_456 (39 events), and user_789 (32 events). These users show strong product-market fit indicators.",
  "confidence": "high",
  "dataPoints": 127
}

Trial Limit Error

402 Payment Required

{
  "error": "Trial limit reached",
  "message": "You have used all 20 trial AI questions. Upgrade to continue.",
  "upgradeUrl": "https://www.revhold.io/dashboard/billing"
}

GET/usage

Retrieve a summary of recent usage events. Useful for building custom dashboards or validating that events are being received. Returns events in reverse chronological order.

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Number of events to return (default: 100, max: 1000)
userId	string	No	Filter events by specific user ID

Response Schema (200 OK)

Field	Type	Description
events	array	Array of event objects
total	number	Number of events returned in this response
limit	number	Limit applied to this query

Example Requests

curl -X GET "https://www.revhold.io/api/usage?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

200 OK

{
  "events": [
    {
      "eventId": "evt_xyz789",
      "userId": "user_abc123",
      "eventName": "feature_used",
      "eventValue": 1,
      "timestamp": "2025-01-02T14:30:00Z"
    }
  ],
  "total": 1,
  "limit": 10
}

Error Codes

The API uses standard HTTP status codes to indicate success or failure. Error responses include a JSON body with additional details.

200 OKSuccess

The request was successful. Response body contains the requested data.

400 Bad RequestClient Error

The request was invalid. Check that all required fields are present and correctly formatted.

{
  "error": "Invalid request",
  "message": "Missing required field: userId",
  "field": "userId"
}

401 UnauthorizedAuthentication Error

Missing or invalid API key. Verify that the Authorization header is set correctly.

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

402 Payment RequiredTrial Limit

Your trial limit has been reached. Upgrade your plan to continue.

{
  "error": "Trial limit reached",
  "message": "You have used all 20 trial AI questions.",
  "upgradeUrl": "https://www.revhold.io/dashboard/billing"
}

429 Too Many RequestsRate Limit

You have exceeded the rate limit. Wait before retrying.

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Try again in 60 seconds.",
  "retryAfter": 60
}

500 Internal Server ErrorServer Error

Something went wrong on our end. If this persists, contact support.

{
  "error": "Internal server error",
  "message": "An unexpected error occurred. Please try again.",
  "requestId": "req_abc123"
}

Rate Limits

Rate limits are enforced per API key across all endpoints. Limits are generous for typical usage patterns but prevent abuse.

Endpoint	Rate Limit	Burst
POST /api/usage	1,000 / minute	100 requests
POST /api/ai	10 / minute	5 requests
GET /api/usage	100 / minute	20 requests

Rate Limit Headers

All API responses include rate limit information in the headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1704201600

Need help?

Have questions about the API? Check the documentation or contact support.

View Documentation Contact Support