Extension API Features
Use this page after Iframe Quickstart to add verified challenges, completion requirements, and lock actions to an extension. The examples use an installed extension's session ID, not its app ID or the lock ID.
Keep the app-scoped Developer API key on your backend. The iframe can show UI and request an action, but its score, timestamps, claimed identity, and success message are not proof of completion. Verify the result and associate it with the correct session before writing progress or applying a reward or punishment.
Feature Map
| Feature | Question it answers | Where it is configured or recorded |
|---|---|---|
| Unlock requirement | Has this session earned enough verified progress to clear a release condition? | config.initialMetadata.unlockRequirements; backend requirements/progress |
| Manual unlock blocker | Has the backend explicitly cleared this release condition? | metadata.unlockBlockers |
| Home action | Which extension activity should the lock page offer? | metadata.homeActions |
| Regular actions | Is an action slot available now? | config.regularActions; backend regular-actions |
| Required progress | Were enough completions recorded in a calendar window? | config.extensionRequirements; backend requirements/progress |
| Attempt limit | Has this particular attempt passed its deadline? | config.attemptLimit; backend attempts/start and attempts/fail-expired |
| Reward or punishment | Which permitted lock action should follow a verified outcome? | Backend action or custom notification endpoint |
These mechanisms do not automatically perform each other's work. Consuming a regular-action slot does not record completion progress. Recording progress does not consume a slot, send a notification, apply a reward, or finish an attempt timer.
Required Backend Headers
Privileged extension-session endpoints require both headers:
Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH
The Developer API key authenticates your backend for its app. The mainToken ties the request to one installed extension session and the user who launched it. A user-wide API key is for /api/apps/v1/*, not these routes.
Reads require locks:read; the writes shown here require locks:write. Effective permissions are the intersection of the launch grant's scopes, the installed extension's current scopes, the app's current allowed scopes, and the Developer key's scopes. The extension must be enabled, its app active, the grant valid, and the lock session still open. A token whose wearer/keyholder role no longer matches the current session is rejected.
Roles still apply
A backend key does not turn a wearer launch into a keyholder launch. Plan the action around the role of the supplied token:
| Action | Additional role conditions |
|---|---|
remove_time, unfreeze, task.complete | Keyholder launch token required. |
toggle_freeze, settings.patch, hygienic_unlock.start | Keyholder launch token required; shared locks also require a trusted keyholder. |
add_time, freeze | Shared locks require a keyholder token. Untrusted time-addition limits still apply. |
pillory.end | Shared locks require a trusted keyholder token. |
pillory | Pillory must be enabled. Untrusted shared keyholders must use its configured duration, respect its cooldown, and cannot extend active Pillory. |
task.assign | Tasks must be enabled. actor: "keyholder" or "wearer" must match the launch role; "extension" records extension attribution. |
State, metadata, regular-action, and progress writes require backend credentials and scopes, but do not require a keyholder role just because they change extension state. Your backend must still enforce its own challenge rules.
Unlock Blockers
Use blockers to add a condition to normal time-based release, such as completing three verified challenges. They do not replace lock time, other release requirements, or Chastify's explicit release and safety paths. Clearing your extension's blocker does not itself unlock the session.
Only enabled extensions contribute blockers. Manual blockers and unmet progress requirements are combined: satisfying one does not remove the others. A home-action button is a way to open the activity; it does not enforce a requirement by itself.
Progress-based blockers
Put the following in the installed extension's configuration, usually returned by your setup UI:
{
"initialMetadata": {
"unlockRequirements": [
{
"metric": "memory_win",
"requiredCount": 3,
"blocker": "Complete 3 memory challenge wins to unlock"
}
],
"homeActions": [
{
"slug": "play-memory-challenge",
"title": "Play memory challenge",
"description": "Complete the required challenge.",
"icon": "gamepad-2",
"badge": "Required"
}
]
}
}
Chastify initializes this metadata when the session starts or a shared template is accepted, before the wearer first opens the extension. Configuration updates can synchronize it again; keep saved configuration and runtime metadata consistent rather than assuming a runtime patch survives every configuration edit.
After verifying a completion, your backend records progress for the same metric:
curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/requirements/progress" \
-H "Authorization: Bearer $DEVELOPER_KEY" \
-H "x-chastify-main-token: $MAIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"metric":"memory_win","amount":1}'
This increases the session's lifetime unlock progress. The matching requirement stops blocking when its count reaches requiredCount; it does not reset each day or week. Increasing the target later uses the count already recorded for that metric.
Use stable, distinct metric names containing letters, digits, _, or -, up to 80 characters. Other characters are normalized to _, so names such as daily.win and daily win would collide. Omit metric only when you intend to use the configured requirement metric, or the default completion.
The metadata API accepts up to 25 unlock requirements, with requiredCount from 1 to 1000. Use one entry per metric to avoid overlapping requirements for the same counter.
Attempt time limits
An attempt limit records a deadline for one metric's current attempt:
{
"attemptLimit": {
"enabled": true,
"metric": "memory_win",
"durationSeconds": 300,
"startPolicy": "activity"
}
}
activitystarts from the backend's activity time, defaulting to the current time.availabilitystarts from the activity's availability time. Configured availability attempts can be initialized at lock start, before the iframe opens. When starting one explicitly, supply the actualavailableAt; the endpoint otherwise falls back to lock start.
Start from your backend with POST /api/extensions/sessions/$SESSION_ID/attempts/start:
{"metric":"memory_win","attemptId":"memory-run-123"}
The endpoint returns attemptLimit, including startsAt and expiresAt. Durations are 60 seconds to 24 hours. Repeating the same active attemptId retains its start time; a different ID replaces that metric's active attempt. Choose IDs on your backend and do not let refreshes create a fresh deadline for an unfinished challenge.
Check expiry with POST /api/extensions/sessions/$SESSION_ID/attempts/fail-expired:
{"metric":"memory_win","attemptId":"memory-run-123"}
The response reports failed: false if the active attempt is not expired, or failed: true with its failure record when it expires. A supplied ID that does not match the active attempt returns 409 attempt_mismatch.
For a custom extension, your backend must arrange expiry checks. A recorded failure does not consume a regular-action slot or apply a punishment; make those calls separately after verifying the result. Progress submission does not clear the active attempt, and there is currently no generic attempts/complete endpoint. Track successful settlement on your backend so a later expiry check cannot punish an already completed challenge.
Manual blockers
Patch runtime metadata when your backend decides whether a release condition is still unmet:
curl -X PATCH "https://chastify.net/api/extensions/sessions/$SESSION_ID/metadata" \
-H "Authorization: Bearer $DEVELOPER_KEY" \
-H "x-chastify-main-token: $MAIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"unlockBlockers":["Complete the current memory challenge to unlock"],
"homeActions":[{
"slug":"play-memory-challenge",
"title":"Play memory challenge",
"badge":"Required",
"intent":{"type":"play","title":"Memory challenge"}
}]
}'
Clear the manual blockers with the same endpoint and {"unlockBlockers":[]}. This leaves home actions and progress-based requirements unchanged. If an unmet unlockRequirements entry remains, clearing unlockBlockers alone will not clear that requirement.
Metadata patches replace each supplied array; omitted fields stay unchanged. Send the complete desired list when updating one of several home actions or blockers. Supported fields are unlockBlockers, unlockRequirements, and homeActions, with a 16 KiB total metadata limit. The API accepts up to 25 manual blockers and 50 home actions.
Home actions need a stable slug and title. Optional description, icon, badge, and intent describe the UI entry point. Treat an incoming intent as a request to open your activity, not as proof that the wearer completed it.
Regularity Feature
Regular actions control available uses. Configure regularActions in the installed extension, or update it from your backend:
curl -X PATCH "https://chastify.net/api/extensions/sessions/$SESSION_ID/regular-actions/config" \
-H "Authorization: Bearer $DEVELOPER_KEY" \
-H "x-chastify-main-token: $MAIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"mode":"non_cumulative","regularitySeconds":3600,"maxActions":1}'
| Mode | Availability |
|---|---|
unlimited | Always available; actionsRemaining is -1, meaning unlimited. |
non_cumulative | One use is available initially. After submission, wait regularitySeconds from that action. Unused uses do not accumulate; maxActions does not make a batch available. |
cumulative | Starts with up to maxActions uses and replenishes one use per interval, capped at maxActions. |
For example, cumulative mode with regularitySeconds: 21600 and maxActions: 4 starts with four stored uses, then earns one every six hours. It is not a strict four-per-calendar-day rule. The configuration endpoint accepts intervals from 60 seconds to 24 hours and capacity from 1 to 1000. It does not accept a weekly interval.
Read GET /api/extensions/sessions/$SESSION_ID/regular-actions for actionsRemaining, nextActionAt, and retained action history. The response calls the interval field regularity. If the app disables regular actions, the endpoint returns 404 regular_actions_disabled.
Submit a trusted use to POST /api/extensions/sessions/$SESSION_ID/regular-actions:
{"payload":{"kind":"checkin","score":92}}
The payload is your descriptive data; Chastify does not validate that its score proves success. An unavailable slot returns 422 with nextActionAt. The retained action state has a 32 KiB limit, so keep payloads small. The separate required progress mechanism checks whether enough verified completions occurred.
Consumption is atomic per session: overlapping requests cannot spend the same available use, and availability reads do not overwrite submissions. The generic endpoint does not accept an idempotency key; retrying a successful request can consume another available use. Do not award a reward just because a preceding availability read showed a slot.
Custom Required Actions
Use extensionRequirements in the installed session's configuration for a recurring completion target:
{
"extensionRequirements": {
"enabled": true,
"metric": "completion",
"requiredCount": 4,
"cadence": {"every":1,"unit":"day","timezone":"UTC"},
"punishment": {
"type": "add_time",
"seconds": 1800,
"reason": "Daily extension requirement missed"
}
}
}
The target supports 1–1000 completions every 1–52 calendar days or weeks. Weeks start on Monday; windows are calendar-aligned, not measured from the last completion. The wearer's configured time zone normally takes precedence over the time zone in this JSON. Read the effective requirement configuration rather than assuming the example forces UTC.
Record a verified completion through requirements/progress:
{"metric":"completion","amount":1}
The body accepts metric, integer amount from 1 to 1000, and an optional ISO occurredAt. Omit occurredAt to use server time; if supplied, derive it from your trusted completion record, not an unverified browser clock. It chooses the cadence window to credit and does not undo a punishment already processed for that window.
Each call increments lifetime unlock progress. When recurring requirements are enabled, it also increments that metric's count in the selected window. Use the configured metric for the recurring target: a different metric has a separate count and does not satisfy it.
Chastify periodically evaluates the immediately preceding completed window for enabled extensions on active sessions. The initial partial window receives grace. The generic scheduler does not promise to replay every older missed window after downtime.
Supported missed-window effects are none, add_time, freeze, and pillory, with a configured duration up to 30 days. A freeze is skipped if already frozen; Pillory requires the lock's Pillory configuration. These effects are separate from an unlock blocker. If missed work should also block time-based release, configure the corresponding release condition explicitly.
Progress calls have no event ID or deduplication field: sending the same completion twice adds it twice. Record your own completion IDs and settlement status before issuing effects, and reconcile uncertain responses instead of blindly replaying increments or rewards. Missed-window effects have durable source records and atomic lock receipts, so recovery finishes bookkeeping without applying the same punishment again. Pillory notification/webhook delivery can repeat after an interruption; delivery retries do not repeat the punishment.
Rewards
Send permitted lock actions to POST /api/extensions/sessions/$SESSION_ID/action after verified success. For example, a keyholder launch token can remove ten minutes:
curl -X POST "https://chastify.net/api/extensions/sessions/$SESSION_ID/action" \
-H "Authorization: Bearer $DEVELOPER_KEY" \
-H "x-chastify-main-token: $MAIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"remove_time","params":600}'
Time changes respect applicable lock limits and frozen state. The request is not a guarantee of immediate release. A wearer token cannot perform remove_time, even when your backend verified a win.
To start a hygienic opening, send {"name":"hygienic_unlock.start","params":{"durationSeconds":900}}. This requires a keyholder token, trusted keyholder access on shared locks, Hygienic Opening enabled, and no hygienic opening or soft emergency release already in progress. See Hygienic Unlock for the user workflow.
Custom notifications use POST /api/extensions/sessions/$SESSION_ID/notifications/custom with the same backend headers:
{"title":"Challenge complete","message":"Your verified result was recorded.","target":"wearer"}
Targets are wearer, keyholder, or both. With both, Chastify targets whichever session participants exist; if no selected recipient exists, the request fails. Titles allow 100 characters and messages 500. An accepted response reports queued dispatch, not guaranteed delivery. A notification does not itself apply the reward described in its text.
Punishments
Use the same action endpoint for a verified failure. The role rules above still apply:
| Effect | Request body |
|---|---|
| Add 30 minutes | {"name":"add_time","params":1800} |
| Freeze for one hour | {"name":"freeze","params":{"durationSeconds":3600}} |
| Assign a 30-minute minimum task | {"name":"task.assign","params":{"actor":"extension","taskText":"Write a short reflection about the missed requirement.","points":5,"durationMinutes":30}} |
| Start Pillory for one hour | {"name":"pillory","params":{"durationSeconds":3600,"reason":"Extension requirement missed"}} |
add_time and remove_time take a number of seconds, with an absolute request limit of 365 days; lock and trust limits can be stricter. Direct freeze accepts 60 seconds to seven days. Pillory accepts 60 seconds to 30 days, subject to its enabled state and keyholder restrictions.
For task.assign, durationMinutes is the minimum task timer, not a completion deadline. Tasks must be enabled, and the session's 10-task capacity still applies. The assignment does not replace an existing task. See Tasks & Task Queue.
Apply only the effects your backend has authorized for that specific outcome. An attempt failure, regular-action submission, or custom notification does not automatically call this endpoint.
Recommended Pattern
- Open the iframe and send its session-bound
mainTokento your backend over your normal authenticated connection. - Resolve the session and check the launch role and scopes before offering an unavailable reward or control.
- Create a backend-owned challenge ID. If using regular actions, serialize and verify slot consumption; if using attempt limits, preserve the active attempt ID and deadline.
- Verify the submitted work and expiry on the backend.
- Record the outcome and settlement status in your backend. Submit the intended progress, reward, punishment, and slot changes as separate operations with tracked results.
- Update manual blockers or home actions when needed. Progress-based blockers evaluate their counter automatically.
- Refresh safe state and metadata in the iframe and show the confirmed result. On an uncertain response, reconcile before offering a retry that repeats an effect.
Keep your own UI data separate from data.requirements and data.attemptLimits. Generic PUT /state replaces the entire data object, and generic patches can also change those namespaces; they are not protected from a credentialed backend overwrite. Preserve their existing contents when updating unrelated state, and use the dedicated progress/attempt routes for their normal operations.
For additional request examples, see API Examples.