Streakfox | Retention through streaks

Use the Events API to record streak events directly. Browser events, server events, webhooks, automations, and MCP calls can all feed the same retention program when they use the same siteKey, userHash, and event key.

Record Event

Records a browser/widget streak interaction for a user. Browser calls are checked against your project's allowed origins.

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"
}

For trusted backend calls, use the signed server endpoint instead. This is the preferred path for purchases, completed jobs, server-side onboarding steps, and other actions that should not depend on browser JavaScript:

curl -X POST https://api.streakfox.com/v1/server/e \
  -H "Content-Type: application/json" \
  -H "X-Streak-Server-Token: $STREAKFOX_SERVER_TOKEN" \
  -d '{
    "siteKey": "proj_abc123",
    "userHash": "user_xyz789",
    "event": "lesson_complete",
    "source": "api",
    "eventType": "streak_interaction"
  }'

For third-party automations, use the per-program webhook endpoint. Create the webhook secret from the dashboard Programs page before sending events:

curl -X POST https://api.streakfox.com/v1/webhook/proj_abc123/e \
  -H "Content-Type: application/json" \
  -H "X-Streak-Webhook-Secret: $STREAKFOX_WEBHOOK_SECRET" \
  -d '{
    "siteKey": "proj_abc123",
    "userHash": "user_xyz789",
    "event": "lesson_complete",
    "eventType": "streak_interaction",
    "externalService": "pipedream"
  }'

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	❌	Compatibility 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
`source`	string	❌	One of `widget`, `api`, `webhook`, `automation`, `mcp` for signed server events
`externalService`	string	❌	Source label such as `zapier`, `pipedream`, or `internal-agent`
`integrationId`	string	❌	Stable identifier for the automation/integration

Response

// Success (202 Accepted)
{ "ok": true }

// Error (400 Bad Request)
{ "error": "INVALID_BODY" }
{ "error": "INVALID_SITE_KEY" }
{ "error": "SITE_KEY_MISMATCH" }
{ "error": "INVALID_WIDGET_KIND" }

// Error (403 Forbidden)
{ "error": "FORBIDDEN_ORIGIN" }

// Error (401 Unauthorized)
{ "error": "SERVER_TOKEN_REQUIRED" }
{ "error": "WEBHOOK_SECRET_REQUIRED" }

// Error (413 Payload Too Large)
{ "error": "PAYLOAD_TOO_LARGE" }

// Error (429 Too Many Requests)
{ "error": "RATE_LIMITED" }

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"
  }'

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.com

Query Parameters

Param	Required	Description
`siteKey`	✅	Your project ID
`userHash`	✅	User identifier
`event`	✅	Widget event (e.g., `visit`, `like`)
`kind`	❌	Compatibility 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), include X-Streak-Server-Token. Compatibility mode may temporarily allow no-origin calls without the token, but this path is deprecated.

Use X-Streak-Webhook-Secret for /v1/webhook/:siteKey/e. Webhook secrets are managed from the dashboard Programs page.