Api
Events API
Record streak events through the REST API.
Use the Events API to record streak events directly, without the widget or SDK.
Record Event
Records a streak interaction for a user.
POST /v1/e HTTP/1.1
Host: api.streakfox.com
Content-Type: application/json
{
"siteKey": "YOUR_PROJECT_ID",
"userHash": "user_abc123",
"event": "like",
"eventType": "streak_interaction",
"ts": "2024-01-15T12:34:56.000Z",
"meta": {
"postId": "123"
},
"idempotencyKey": "unique-event-id"
}Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
siteKey | string | ✅ | Your project ID (also called API key) |
userHash | string | ✅ | Unique identifier for the user |
event | string | ✅ | Action type matching your widget configuration |
kind | string | ❌ | Legacy alias for event |
eventType | string | ❌ | Event type: streak_interaction (default), widget_impression |
ts | ISO 8601 | ❌ | Event timestamp (defaults to server time) |
tz | string | ❌ | User's timezone (e.g., America/New_York) |
meta | object | ❌ | Custom metadata for analytics |
idempotencyKey | string | ❌ | Unique key to prevent duplicate processing |
sessionId | string | ❌ | Group events by session |
Response
// Success (202 Accepted)
{ "ok": true }
// Error (400 Bad Request)
{ "error": "INVALID_BODY" }
{ "error": "INVALID_SITE_KEY" }
{ "error": "INVALID_WIDGET_KIND" }
// Error (403 Forbidden)
{ "error": "FORBIDDEN_ORIGIN" }cURL Example
curl -X POST https://api.streakfox.com/v1/e \
-H "Content-Type: application/json" \
-d '{
"siteKey": "proj_abc123",
"userHash": "user_xyz789",
"event": "like",
"eventType": "streak_interaction"
}'Get Widget State
Fetches the current streak state for a user.
GET /v1/state?siteKey=PROJECT_ID&userHash=USER_HASH&event=like HTTP/1.1
Host: api.streakfox.comQuery Parameters
| Param | Required | Description |
|---|---|---|
siteKey | ✅ | Your project ID |
userHash | ✅ | User identifier |
event | ✅ | Widget event (e.g., visit, like) |
kind | ❌ | Legacy alias for event |
Response
{
"meta": {
"apiVersion": "1",
"isLive": true
},
"streak": {
"mode": "continuous",
"current": 5,
"best": 12,
"todayDone": true,
"pending": false
},
"week": [
{ "isoDate": "2024-01-08", "label": "Mon", "dayNumber": 8, "isToday": false, "isCheckedIn": true },
{ "isoDate": "2024-01-09", "label": "Tue", "dayNumber": 9, "isToday": false, "isCheckedIn": true },
// ... 7 days total
],
"milestones": [
{ "id": "ms_1", "target": 7, "msg": "1 week!", "achieved": false, "rewardType": "message" }
],
"settings": {
"theme": { "name": "beige" },
"position": "bottom-right",
"mainMessage": "Keep your streak going!"
}
}Alias User (Admin)
Links an anonymous visitor to an authenticated user. Requires admin token.
POST /admin/alias HTTP/1.1
Host: api.streakfox.com
X-Admin-Token: YOUR_ADMIN_TOKEN
Content-Type: application/json
{
"siteKey": "PROJECT_ID",
"anonymousId": "anon_visitor_id",
"userHash": "authenticated_user_hash"
}Response
204 No Content (success)
401 Unauthorized (invalid token)
400 Bad Request (missing fields)Event Types
| Type | Description |
|---|---|
streak_interaction | User action that counts toward streak (default) |
widget_impression | Widget was viewed (analytics only) |
widget_interaction | Widget expand/collapse (analytics only) |
CORS & Origins
The API validates the Origin header against your project's allowed domain. Ensure your domain is configured in the project settings.
For server-side requests (no Origin header), all requests are allowed.
Idempotency
- Events are deduplicated per user/widget/day for
streak_interactionevents - Optionally provide an
idempotencyKeyfor additional deduplication - Idempotency keys expire after 24 hours
Usage Limits
| Plan | Active streakers / month |
|---|---|
| Starter | 500 |
| Growth | 2,500 |
| Scale | 10,000 |
| Pro | 50,000 |
An active streaker is a unique visitor who triggers a streak interaction during the month.
Next Steps
- Web SDK — Type-safe SDK for easier integration
- Action-Based Streaks — Trigger from code
- Connecting Users — Merge anonymous and authenticated