BlockMe API

Use the REST API to synchronize focus settings, upload per-device browsing totals, inspect connected devices, and generate productivity summaries. Create and revoke keys under Dashboard → API keys.

Authentication

Send the API key as a bearer token over HTTPS. Keep it out of source control, logs, prompts that may be retained, and client-side applications.

Authorization: Bearer bm_your_api_key

Invalid, expired, or revoked keys return 401. Extension sign-in creates a device-bound key. Re-authenticating from the extension sends the existing deviceId as existingDeviceId in the POST /api/v1/auth/login body so the server reattaches a fresh key to the same device instead of registering a duplicate. General dashboard keys can read usage and manage configuration; only a device-bound key can upload usage.

POST /api/v1/auth/login and POST /api/v1/auth/signup are rate-limited per IP; excessive attempts return 429.

Configuration sync

GET /api/v1/sync returns the current revision, groups, whitelist, and blocking settings. Writes are revision-safe: send the current revision as baseRevision with PUT /api/v1/sync. A stale write returns 409 REVISION_CONFLICT; fetch the latest state, merge deliberately, and retry. The extension auto-merges conflicts by unioning local and remote blocked sites (deduped) and pushing the merged result; the master toggle and strict-subdomain setting follow the cloud. A site deleted on the cloud re-appears if it is still present locally — the accepted tradeoff of union-merge.

GET https://blockmemotherfocus.apercallc.com/api/v1/sync
Authorization: Bearer $BLOCKME_API_KEY

PUT https://blockmemotherfocus.apercallc.com/api/v1/sync
Authorization: Bearer $BLOCKME_API_KEY
Content-Type: application/json

{"baseRevision":12,"settings":{"enabled":true,"strictSubdomains":false},"blockedGroups":[{"name":"Deep Work","enabled":true,"sites":["youtube.com","reddit.com"]}],"whitelist":["music.youtube.com"]}

Raw usage

GET /api/v1/usage?days=7 returns account-wide domain/category/day totals aggregated across devices. days accepts 1–90 and defaults to 7. Add &groupBy=device to include device ID, name, and platform on each row.

GET https://blockmemotherfocus.apercallc.com/api/v1/usage?days=7&groupBy=device
Authorization: Bearer $BLOCKME_API_KEY

{"days":7,"groupBy":"device","usage":[{"deviceId":"...","deviceName":"Work laptop","platform":"chrome","domain":"github.com","category":"productivity","date":"2026-07-21","durationMs":3600000}]}

POST /api/v1/usage upserts the calling device’s daily total for each domain. Retries are idempotent and other devices remain independent. Requests accept 1–5,000 entries and cap each device/domain/day at 24 hours.

POST https://blockmemotherfocus.apercallc.com/api/v1/usage
Authorization: Bearer $BLOCKME_API_KEY
Content-Type: application/json

{"entries":[{"domain":"github.com","date":"2026-07-21","durationMs":3600000}]}

DELETE /api/v1/usage permanently clears cloud usage for every device on the account. It does not clear local extension history. DELETE /api/v1/auth revokes the calling key, disconnecting the device; the extension calls it on sign-out so a captured key stops working immediately. A password reset also revokes all of the account's API keys, forcing every device to re-authenticate.

Bypass activity

When you weaken your own blocking — pausing the master switch, disabling a group, or removing a site — the extension records a timestamped bypass event and syncs it to your account. Events are domains and action metadata only, never full URLs.

POST /api/v1/bypass-events upserts the calling device’s bypass events. Retries are idempotent by the device-supplied event id; other devices stay independent. Requests accept 1–5,000 entries.

POST https://blockmemotherfocus.apercallc.com/api/v1/bypass-events
Authorization: Bearer $BLOCKME_API_KEY
Content-Type: application/json

{"entries":[{"id":"evt-1","ts":1753324800000,"action":"master-pause"}]}

GET /api/v1/bypass-events?days=7 returns the period total, bypass total (weakening actions only), per-action counts, daily counts, and the top 20 bypassed domains. days accepts 1–90 and defaults to 7.

GET https://blockmemotherfocus.apercallc.com/api/v1/bypass-events?days=7
Authorization: Bearer $BLOCKME_API_KEY

The usage summary (GET /api/v1/usage/summary) additionally returns timeOnCurrentlyBlockedMs and blockedSiteCount — time spent on domains currently in your block list. This may include time from before you blocked them, since the block list is a point-in-time state.

Block attempts

When a navigation to a blocked domain is stopped, the extension records a timestamped block-attempt event and syncs it to your account. Events contain only a domain and timestamp, never a full URL. Repeat hits on the same domain within 30 seconds are counted once.

POST /api/v1/block-attempts idempotently upserts 1–5,000 events for the calling device. GET /api/v1/block-attempts?days=7 returns the total, daily counts, and top 20 attempted domains for a 1–90 day period.

POST https://blockmemotherfocus.apercallc.com/api/v1/block-attempts
Authorization: Bearer $BLOCKME_API_KEY
Content-Type: application/json

{"entries":[{"id":"evt-1","ts":1753324800000,"domain":"reddit.com"}]}

GET https://blockmemotherfocus.apercallc.com/api/v1/block-attempts?days=7
Authorization: Bearer $BLOCKME_API_KEY

Productivity summary

GET /api/v1/usage/summary?days=7 returns total, productive and unproductive milliseconds, productive percentage, daily totals, category shares, and the top 20 domains. It also returns the account timezone used for the date window.

By default, productivity, development, education, and ai count as productive. Override that definition per request with repeated or comma-separated productiveCategory parameters.

GET https://blockmemotherfocus.apercallc.com/api/v1/usage/summary?days=30&productiveCategory=productivity,development,design
Authorization: Bearer $BLOCKME_API_KEY

Connected devices

GET /api/v1/devices returns each registered device’s ID, display name, platform, connection status, creation time, last-seen time, and last-sync time. It never returns API keys or key hashes. “Connected” means the device has at least one unrevoked, unexpired key.

What usage data means

BlockMe records the active domain and elapsed active-tab time—not full URLs, page contents, searches, keystrokes, or network traffic. Tracking pauses when the browser loses focus or the computer becomes idle or locked. Browser-internal and extension pages are excluded. Categories are domain-based heuristics and may not reflect the purpose of a particular visit.

AI assistant prompt

You can read my BlockMe account at https://blockmemotherfocus.apercallc.com/api/v1 using a bearer key that must remain secret. Use GET /usage/summary?days=7 for productivity summaries, GET /usage?days=7&groupBy=device only when device attribution is needed, and GET /devices for connection status. GET /sync before proposing configuration changes. Preserve unknown groups and sites. Never PUT a change until I approve it; include the returned baseRevision. On 409, fetch the latest state, explain and merge the conflict, then ask before retrying. Never DELETE usage without explicit confirmation.

Limits and privacy

Sync accepts up to 100 groups and 1,000 sites per group. Usage reads cover at most 90 days per request. Cloud sync is optional; without extension sign-in, browsing data remains local. Domain-level history can reveal sensitive interests, so grant keys only to systems you trust and revoke unused keys from the dashboard.