Skip to main content

External API & Programs

Use a user-wide Developer API key for a private script or backend that works with active locks where you are the wearer or current keyholder. No extension installation is required. Keep the key in your trusted local program or server environment.

For a public installed extension, use API Examples with an app-scoped key and launch token. For consent-based, read-only account linking, use Connect Chastify with OAuth. These credentials are not interchangeable.

Create A DEV Token​

  1. Open Developer API in Chastify and find the Developer API key form.
  2. Give the key a recognizable name, such as “Local test server”.
  3. Select Key type → User-wide and choose Create DEV key.
  4. Copy the full key when it appears. It is only shown once.

Keys remain valid until revoked and may access later active sessions, subject to your role, scopes, and account safeguards. Revoke an unused or exposed key on the same page. There is a limit of 25 active keys per account.

The key-creation safeguard is enabled by default: ordinary accounts cannot create a new key while wearing an active lock. A separate personal key use safeguard can block existing user-wide keys when you are the wearer. Keyholder requests still follow the selected lock's permissions. Plan your integration before starting a lock; do not treat either safeguard as an API failure to work around.

Requests use:

Authorization: Bearer YOUR_DEV_TOKEN

The examples below assume CHASTIFY_DEV_TOKEN is already loaded securely into your environment. Do not put a real key in a repository, frontend bundle, shared command transcript, or log.

First Call: Check The Current Lock​

Start with a read:

curl --fail-with-body "https://chastify.net/api/apps/v1/session" \
-H "Authorization: Bearer $CHASTIFY_DEV_TOKEN"

This requires locks:read and returns lock context, your role/scopes, and lockData. If you have multiple active locks, the automatic selection can change as locks are updated. Inspect the returned lock._id, then pin the intended ID in CHASTIFY_LOCK_ID and send it on every subsequent request:

curl --fail-with-body "https://chastify.net/api/apps/v1/session" \
-H "Authorization: Bearer $CHASTIFY_DEV_TOKEN" \
-H "x-chastify-lock-id: $CHASTIFY_LOCK_ID"

Use the exact 24-character hexadecimal ID returned by Chastify. Confirm that lock._id matches your intended target before enabling writes. Empty, malformed, or conflicting selectors return 400 invalid_selector for reads and writes. A valid unavailable or unauthorized target returns 409 no_active_lock_session; neither case falls back to another lock. Omit selectors only when you want automatic selection. An ID does not grant access to another person's lock. See the supported selector aliases.

Lock Data Helpers​

The session response groups built-in on/off flags and installed-extension statuses in modules. See Module status for the complete shape and examples of listing enabled and disabled modules. The same summary is available to OAuth integrations and installed extensions.

FieldHow to use it
role and scopesCheck which account role and granted capabilities the request uses.
lockData.frozenWhether the timer is currently frozen. A hygienic opening can also keep it paused.
lockData.trustedTrust context for the keyholder; individual actions still enforce their rules.
lockData.taskAssignedWhether an open task run exists, not which task a later action will select.
timeRemainingSeconds, maxTimeRemainingSeconds, timeLockedSecondsTiming helpers; allow null when timing is hidden.
taskPoints, taskPointsRequiredTask progress values, not the complete unlock requirements.

The timing and task fields in the last two rows are under lockData. Do not interpret a zero timer, isLocked, or unlockable alone as permission to open a device or end the lock. Use Chastify's normal unlock flow for the complete checks.

Wearer/keyholder identity and media fields can be nullable. Last-seen timestamps respect online-status visibility, and signed image URLs expire. See media fields and privacy.

Main Lock Action Endpoints​

All paths below start with https://chastify.net. Reads require locks:read; writes require locks:write, a valid user-wide key, and applicable lock permissions.

Method and pathPurpose
GET /api/apps/v1/sessionInspect the selected lock and caller context.
POST /api/apps/v1/lock/apply-timeApply a signed time delta.
POST /api/apps/v1/lock/freezeFreeze the timer.
POST /api/apps/v1/lock/unfreezeRemove the ordinary freeze.
POST /api/apps/v1/actionTask, pillory, hygiene, settings, and time actions.
POST /api/apps/v1/logs/customAdd a custom lock-history entry.
POST /api/apps/v1/notifications/customSend a custom notification to available lock participants.
POST /api/apps/v1/device-commandRequest a supported device effect or stop.
GET, PUT, PATCH /api/apps/v1/stateStore/read program data for this key owner and selected lock.
GET, PATCH /api/apps/v1/metadataRead/write that program's metadata.

Send the bearer token and x-chastify-lock-id on every request. For JSON bodies, also send Content-Type: application/json.

State writes use { "data": ... }, with a 64 KiB limit. PUT replaces data; PATCH merges objects, deletes keys set to null, and replaces arrays. Metadata supports unlockBlockers and homeActions within 16 KiB. This personal-program storage is separate from an installed extension's session state; do not assume it configures that extension's requirements or actions.

Add Or Remove Time​

Use /lock/apply-time for a signed integer delta. Positive adds time; negative removes time. The accepted magnitude is at most 365 days in seconds, with lock limits and untrusted-keyholder budgets enforced separately.

Add ten minutes:

curl --fail-with-body -X POST "https://chastify.net/api/apps/v1/lock/apply-time" \
-H "Authorization: Bearer $CHASTIFY_DEV_TOKEN" \
-H "x-chastify-lock-id: $CHASTIFY_LOCK_ID" \
-H "Content-Type: application/json" \
-d '{"deltaSeconds":600}'

To remove five minutes, change the body to { "deltaSeconds": -300 }. Shared-lock time changes require the keyholder. The response includes remainingSecondsBefore, remainingSecondsAfter, and releaseAt; use the returned values instead of assuming the requested delta produced that exact remaining time.

Time changes are not safe to repeat blindly

These requests do not take an idempotency key. If the connection fails after submission, a second request can apply the change twice. Check the lock/history and your own operation record before deciding whether to submit again.

Freeze And Unfreeze​

Freeze for 30 minutes:

curl --fail-with-body -X POST "https://chastify.net/api/apps/v1/lock/freeze" \
-H "Authorization: Bearer $CHASTIFY_DEV_TOKEN" \
-H "x-chastify-lock-id: $CHASTIFY_LOCK_ID" \
-H "Content-Type: application/json" \
-d '{"durationSeconds":1800}'

This user-wide endpoint accepts 60–86,400 seconds and defaults to 3,600 seconds. Shared-lock freeze/unfreeze requires the keyholder.

Unfreeze with the same headers and POST /api/apps/v1/lock/unfreeze; no body is required. Inspect the returned frozen value: an active hygienic opening can keep the timer paused. Removing an ordinary freeze does not end that opening.

General Action Endpoint​

Send a named action to POST /api/apps/v1/action:

{ "name": "add_time", "params": 600 }

Unlike /lock/apply-time, add_time and remove_time choose the sign themselves. Both use the absolute magnitude of params. To subtract five minutes, use remove_time with 300; a negative add_time value still adds time.

Supported Action Names​

ActionParameters and main conditions
add_time, remove_timeNumber of seconds; shared-lock changes require the keyholder.
freeze{ "durationSeconds": 1800 }; 60–86,400 seconds, default 3,600. Shared lock: keyholder.
unfreezeNo parameters. Shared lock: keyholder.
toggle_freezeOptional duration as for freeze; shared lock: keyholder. Read state first to avoid reversing the wrong state.
pilloryOptional durationSeconds and reason; requires enabled, inactive pillory and applicable cooldown.
pillory.endNo parameters; shared lock: trusted keyholder.
settings.patchSupported visibility settings; shared lock: trusted keyholder. A self-lock wearer cannot use this to reveal hidden information again.
task.assignRequired actor and task text/title; Tasks must be enabled.
task.start_timerNo parameters; targets the newest open timed task run.
task.complete{ "successful": true } or { "successful": false, "reason": "..." }; successful completion checks verification, timer, and deadline.
hygienic_unlock.startOptional duration; requires enabled, eligible Hygienic Opening and no hygienic opening or soft emergency release already in progress.

These are the user-wide route's conditions, not the installed-extension role table. The server checks the current role, active session, settings, and trust on every request; having locks:write alone does not authorize every action.

Useful Action Examples​

Assign a ten-minute task:

{
"name": "task.assign",
"params": {
"actor": "extension",
"title": "Complete your check-in",
"description": "Record today's result.",
"points": 2,
"durationMinutes": 10,
"verificationRequired": false
}
}

actor is required. wearer and keyholder must match your actual role; extension attributes the assignment to the integration. Titles allow up to 120 characters, descriptions up to 500, points 0–100, and duration 0–1,440 minutes. Legacy durationSeconds is converted to minutes rounded up.

Assignment creates an additional run subject to queue and selection limits; it does not replace all existing tasks. task.start_timer and task.complete select the most recently created open task run, with no task ID parameter. Do not chain them when another task may have been assigned meanwhile. Restarting a timer resets its completion time from now.

Successful completion needs a started and finished timer when the task has a duration, and must occur within its deadline. Photo-verification tasks must use the verification flow, not direct successful completion. See Tasks & Task Queue for how runs appear to the wearer.

Start pillory:

{
"name": "pillory",
"params": { "durationSeconds": 3600, "reason": "Verified missed activity" }
}

Duration accepts 60 seconds to 30 days. Omitting it uses the lock's configured initial duration, or one hour. An untrusted shared keyholder must use that initial duration and obey the cooldown. An already active pillory returns a conflict.

Begin an eligible hygienic opening:

{ "name": "hygienic_unlock.start", "params": { "durationSeconds": 900 } }

The user-wide endpoint checks the lock's opening eligibility and configured allowance. It may reject an opening that needs location evidence. This starts the hygienic-opening workflow, not a generic physical device unlock. See Hygienic Unlock.

Custom Lock Log​

Send to POST /api/apps/v1/logs/custom:

{
"title": "Daily check-in recorded",
"description": "The program accepted the verified activity.",
"role": "extension",
"icon": "check",
"color": "#22c55e"
}

title is required and allows 1–180 characters. Optional description allows up to 2,000; icon up to 80; color must be a three- or six-digit hex color. role defaults to extension; logging as wearer or keyholder requires that actual role. This records history; it does not itself apply the effect described in the text.

For a notification, use /notifications/custom with { "title": "...", "message": "...", "target": "wearer", "showPageOverlay": false }. Titles allow 100 characters, messages 500; target can be wearer, keyholder, or both. Success is not proof that someone read it.

Device Commands​

Use POST /api/apps/v1/device-command with locks:write. The command targets the selected lock's wearer, using your actual wearer/keyholder role. Consent, configured device capabilities, keyholder policy, and delivery availability still apply.

Request body​

{
"command": "vibration.start",
"params": { "durationSeconds": 5, "intensityPct": 20, "frequencyPct": 50 }
}

Send explicit finite numeric values. The route rounds and clamps numeric settings; device policy can adjust the final effect further. Check the wearer's configured device and supported features before offering controls, and handle rejection if the device or permissions change. The user-wide session response does not include the installed iframe's deviceControl capability object.

Supported commands and their params​

shock.start​

{
"command": "shock.start",
"params": { "durationSeconds": 5, "intensityPct": 20 }
}

durationSeconds is clamped to 1–300, default 60. intensityPct is clamped to 1–100, default 50; optional message supplies context. Device models map percentages to their supported levels. The applicable keyholder policy may mirror wearer settings, allow the maximum, or use custom limits, so a percentage is not a promise about a particular voltage or physical sensation.

This can enter a delivery queue. A successful submission does not necessarily mean the effect has started or finished.

shock.stop​

{ "command": "shock.stop" }

Requests stopping active shocks and associated stop handling. It is not a guarantee that every future mandatory delivery is cancelled. The response can report that a stop was requested even when no device socket is active.

vibration.start​

{
"command": "vibration.start",
"params": { "durationSeconds": 5, "intensityPct": 20, "frequencyPct": 50 }
}

Duration is 1–300 seconds, default 30. Intensity and frequency are 1–100, each defaulting to 50. message is optional. Support and routing depend on the configured vibration-capable device; commands may use an eligible secondary device where that fallback is supported.

vibration.stop​

{ "command": "vibration.stop" }

Requests stopping active vibration. Successful server handling is not a physical acknowledgement from an offline device.

all.stop​

{ "command": "all.stop" }

Attempts both shock and vibration stops even if one fails. A failed or unconfirmed child operation produces success: false and an error HTTP status (normally 503), with a message describing both outcomes. Successful handling confirms acceptance of the stop requests, not physical device acknowledgement. Mandatory delivery obligations keep their existing cancellation policy; check delivery status when confirmation matters.

shock.random.set​

{
"command": "shock.random.set",
"params": {
"enabled": true,
"durationSeconds": 30,
"minIntensityPct": 20,
"maxIntensityPct": 50
}
}

Lockink AA-A1012 only. This is a timed random-mode request: duration 1–300 seconds, default 60. Minimum/maximum percentages are each 1–100, defaulting to 20 and 80; send minimum no greater than maximum. message is optional.

{ "enabled": false } requests a stop. Where the caller is permitted, it can also cancel that caller's eligible controller requests; do not treat it as cancelling all lock-generated delivery obligations.

shock.berserk.set​

{
"command": "shock.berserk.set",
"params": { "enabled": true, "durationSeconds": 30 }
}

Lockink AA-A1012 only. Duration is 1–300 seconds, default 60; message is optional. The service applies the current device/role policy to this timed mode. { "enabled": false } requests stopping with the same controller-cancellation limitations as random mode.

Device selection​

The API resolves the wearer's configured eligible device; these command bodies do not accept an arbitrary device ID. Shock selection uses an active, fully configured supported device, and vibration has its own selection/fallback path. Do not assume every wearer has exactly one device or that every device supports every command.

Delivery can use a connected browser, a native app route, or supported Cellmate Pro 3 4G delivery. Queue availability and acknowledgements depend on the route. A closed app is not a universal explanation for failure, and a configured device is not proof of current connectivity. See Supported Devices and Shock Delivery & Queues.

Responses​

Success (200)​

The response has this general shape; result fields vary by command and delivery route:

{
"ok": true,
"command": "shock.start",
"result": {
"success": true,
"queued": true,
"message": "Shock queued for delivery"
},
"active": { "shock": false, "vibration": false }
}

A queued result may also contain deliveryEventId, queuePosition, and expiresAt. Preserve those fields when present and show a queued state. Immediate results may instead include acknowledgement/duration/device information. The active flags are a snapshot, not a delivery receipt.

Failure​

Service failures generally include ok: false, error, and a message, with optional device information. Authentication, validation, and lock-state failures can use a different body shape. Check the HTTP status first, then retain the server's error code and message.

A timeout can mean the result was not confirmed, not that nothing happened. Do not automatically submit the start command again.

Common failure scenarios explained​

  • No eligible device: the current device lacks the required capability, is inactive, or is not fully configured. Recheck the wearer's device settings and supported commands.
  • Consent or policy rejection: the wearer/keyholder relationship and configured permission must allow that source. Repeated calls do not change authorization.
  • No usable route or failed acknowledgement: check the relevant app/browser/Bluetooth or 4G connection. Some delivery paths queue instead of failing immediately.
  • Unsupported mode: random and berserk require AA-A1012, even if another device supports ordinary shocks.
  • Queue or temporary service limits: follow the returned explanation and inspect delivery status before resubmitting an effect.

Use the delivery guide for queue expiry, recovery, and why a stop can leave outstanding mandatory work.

Common Errors​

Status/codeWhat to check
401Missing, invalid, or revoked credentials.
403 insufficient_scopeThe key needs the route's read/write scope.
403 user_wide_dev_key_requiredUse a user-wide key for these program routes.
403 personal_dev_api_key_blocked_while_lockedThe wearer enabled the personal-key use safeguard.
403 with role/trust errorsThe current lock role or trust does not permit that action.
409 no_active_lock_session / lock_endedVerify the explicit lock ID and whether its session is still eligible.
400 / 409 task or feature errorsCheck enabled modules, task selection, timer, verification, and current state.
413 payload_too_largeReduce state or metadata to the returned limit.
429Respect rate/cooldown limits; inspect the response before scheduling another request.
503 / 504 device/service errorsInspect the message and delivery state; do not equate an unconfirmed result with a safe-to-repeat effect.

Practical Pattern​

Keep one target lock ID and one key in your trusted program configuration. Read context first and check the returned ID before proceeding:

const token = process.env.CHASTIFY_DEV_TOKEN;
const lockId = process.env.CHASTIFY_LOCK_ID;
if (!token || !lockId || !/^[0-9a-fA-F]{24}$/.test(lockId)) {
throw new Error('Configure a Developer key and valid target lock ID');
}

const response = await fetch('https://chastify.net/api/apps/v1/session', {
headers: {
Authorization: `Bearer ${token}`,
'x-chastify-lock-id': lockId,
},
});
const context = await response.json();
if (!response.ok) throw new Error(context.message ?? context.error ?? 'Session request failed');
if (String(context.lock?._id) !== lockId) throw new Error('Unexpected target lock');

console.log({ role: context.role, scopes: context.scopes, lockId });

For writes, validate your own activity or user instruction, choose a bounded effect, send it once with the same target header, and record the returned outcome. Refresh context after a change. If a mutation's response is lost, stop that operation for reconciliation instead of repeating a whole reward/punishment sequence.