Streaks

Streak definitions describe the rules that user streaks follow. Per-user streak state is created and updated automatically by the streak evaluator and the POST /client/streaks/:streakId/qualify endpoint.

Endpoints

POST /admin/projects/:projectId/streaks

Request

Response 201

{
  "data": {
    "id": "…",
    "key": "daily_workout",
    "name": "Daily Workout",
    "qualifying_event": "workout_completed",
    "period": "daily",
    "grace_period_hours": 0,
    "freeze_enabled": false,
    "max_freezes": 1,
    "created_at": "…"
  }
}

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/streaks'

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/streaks' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /admin/projects/:projectId/streaks

{ "data": [{ "id": "…", "name": "…", "qualifying_event": "…", "period": "daily" }] }

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/streaks'

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/streaks' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

PATCH /admin/projects/:projectId/streaks/:streakId

Updatable fields: name, description, qualifying_event, period, grace_period_hours, freeze_enabled, max_freezes, freezes_per_n_events.

key is immutable — it cannot be changed after creation. Clients that qualify by key rely on the key being stable; changing it would silently break their qualify calls.

Errors

• 404 NOT_FOUND.
• 500 UPDATE_FAILED.

Try it:

curl -X PATCH 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/streaks/%7B%7BstreakId%7D%7D'

Curl:

curl -X PATCH '${BASE_URL}/admin/projects/{projectId}/streaks/{streakId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/streaks/:streakId

{ "data": { "deleted": true } }

Try it:

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/streaks/%7B%7BstreakId%7D%7D'

Curl:

curl -X DELETE '${BASE_URL}/admin/projects/{projectId}/streaks/{streakId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

POST /admin/projects/:projectId/streaks/:streakId/reset

Per-user streak correction for support — fix a wrongly-broken streak (for example, a grace-period miss caused by an outage). Sets the user's current_count and marks the streak active again. The update and its audit row commit atomically; a streak_events row with event_type = "reset" is written for the trail.

• Omit set_count to zero the streak — a clean restart.
• Pass set_count to restore the streak to a specific value; longest_count is bumped if set_count exceeds it.

This is a correction primitive, not a provisioning one: it won't create a user's first-touch streak state (the streak evaluator owns that on the first qualifying event), so it returns 404 when no per-user streak row exists yet.

Request (ResetStreakInput)

Response 200

{
  "data": {
    "id": "us_…",
    "app_user_id": "…",
    "streak_definition_id": "…",
    "current_count": 7,
    "longest_count": 7,
    "status": "active",
    "updated_at": "…"
  }
}

Errors

• 400 VALIDATION_ERROR — app_user_id missing.
• 400 INVALID_COUNT — set_count isn't a non-negative integer.
• 400 INVALID_ID — app_user_id or streakId isn't a UUID.
• 404 USER_STREAK_NOT_FOUND — no per-user streak row exists for this (user, streak definition) pair yet.
• 500 RESET_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/streaks/%7B%7BstreakId%7D%7D/reset'

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/streaks/{streakId}/reset' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "app_user_id": "…", "set_count": 7 }'

POST /admin/projects/:projectId/users/:userId/streaks/:streakDefinitionId/grant-shield

Grant N shields (freezes) to a specific user's streak. Increases freezes_remaining by count, clamped at the streak definition's max_freezes.

The endpoint refuses to provision a user's first-touch streak state — the streak evaluator does that automatically on the user's first qualifying event. Grant-shield is meant for top-ups, not first-touch provisioning.

Request

Response 200

{
  "data": {
    "id": "us_…",
    "app_user_id": "…",
    "streak_definition_id": "…",
    "current_count": 7,
    "freezes_remaining": 2,
    "status": "active",
    "updated_at": "…"
  }
}

Errors

• 400 INVALID_COUNT — count must be a positive integer.
• 400 INVALID_ID — userId or streakDefinitionId is not a UUID.
• 404 STREAK_DEFINITION_NOT_FOUND — no streak definition matches streakDefinitionId.
• 404 USER_STREAK_NOT_FOUND — the user hasn't qualified for this streak yet (no state exists to grant against).

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/users/{userId}/streaks/{streakDefinitionId}/grant-shield' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "count": 1 }'