What the app blocker API can do
The Curbox API is a local Android Binder service with an AIDL interface. There is no HTTP server, API key, OAuth flow or remote endpoint. Your app talks to Curbox on the same phone, and the user decides which apps may connect. An approved app can:
- Discover existing focus, app blocker, keyword, grayscale and automatic DND groups.
- Start a manual focus session with an existing group, or stop one when early exit is allowed.
- Run or join a Pomodoro cycle and read its phase (version 7).
- Create, edit or delete focus groups: name, apps, websites, block mode and exit rule (version 7).
- Enable or disable existing app blocker, keyword and grayscale groups.
- Toggle the keyword blocker, reel blocker, UI hider and reel counter globally.
- Request a Do Not Disturb change.
- Read today's screen time, reel count and focus state, plus daily app and website usage for the retained days.
- Get a callback when focus changes, and ask Curbox to keep a companion process running (version 6).
- Register its own named unlock requirements for the user to pick on the pause screen.
It deliberately does not let you create or edit app blocker groups, change a group's apps, schedules, limits or warning settings, attach your requirement to a group yourself, edit UI hider scripts, or touch anti-uninstall. Those stay in the user's hands.
Curbox API vs Android's UsageStatsManager
Android's own UsageStatsManager gives an app raw usage events once the user grants usage access in Settings. It is a data source. If you want blocking, you then have to build the accessibility service, overlays, schedules and tamper resistance yourself, and ask users to trust your app with all of it.
The Curbox API is the other half. Curbox already holds the accessibility permission and does the blocking; your app asks it to act. You also get data UsageStatsManager does not have, such as per-domain website time from supported browsers and the day's short-form video count. Many apps will want both: their own usage access for fine-grained events, and Curbox for enforcement.
Project setup
Enable AIDL and copy the published AIDL files into your app at the same package path, neth/iecal/curbox/api/. Keep the package, method order and signatures unchanged. The interface is small:
ICurboxApi.aidl · ICurboxListener.aidl
package neth.iecal.curbox.api;
interface ICurboxApi {
int apiVersion();
boolean isGranted();
String execute(String command, in Bundle args);
String query(String state);
String list(String kind);
void addListener(ICurboxListener listener); // version 6
void removeListener(ICurboxListener listener); // version 6
}
oneway interface ICurboxListener {
void onChanged(String what);
}
On Android 11 and newer, add these queries directly under <manifest> so your app can discover Curbox. You do not need INTERNET or QUERY_ALL_PACKAGES to use the API.
AndroidManifest.xml
<queries>
<intent>
<action android:name="neth.iecal.curbox.api.BIND" />
</intent>
<intent>
<action android:name="neth.iecal.curbox.api.REQUEST_PERMISSION" />
</intent>
</queries>
Release builds use the package neth.iecal.curbox and debug builds neth.iecal.curbox.debug. Discover the service by the BIND action rather than assuming one package, and if several installs answer, let the user choose. Use the same install for binding and approval.
User approval
The API is off by default and binding alone grants nothing. Your Activity launches the neth.iecal.curbox.api.REQUEST_PERMISSION activity for result, so Android supplies a verified calling package, and the user approves your app in Curbox's dialog. Approval also switches on the global API toggle.
- Grants are tied to your package and its current signing certificates. A signing key change needs fresh approval.
- Users can revoke one app, or turn the whole API off, under Reducers → Curbox API → Connected apps.
- Uninstalling your app ends its grant. Reinstalling needs fresh approval.
- Authorization is broad. There is no read-only scope, so tell users what your app will do before you open the prompt.
Making calls
Calls are synchronous Binder calls, so run them off the UI thread and catch RemoteException and DeadObjectException. execute() returns one of four status strings: OK, DENIED, UNKNOWN_COMMAND or FAILED. query() and list() return JSON strings, or null on denial or failure. Names are case sensitive. Check apiVersion() before using newer features.
This example from the API guide lists focus groups and starts a 25-minute session:
Kotlin · start a focus session
val raw = withContext(Dispatchers.IO) { remote.list("FOCUS_GROUPS") }
val groups = raw?.let(::JSONArray) ?: return
if (groups.length() == 0) return // Ask the user to create a group in Curbox.
// In a real UI, let the user choose a group rather than always choosing index 0.
val groupId = groups.getJSONObject(0).getString("id")
val status = withContext(Dispatchers.IO) {
remote.execute("START_FOCUS", Bundle().apply {
putString("target", groupId)
putInt("minutes", 25)
})
}
OK can mean "stored for later". A session the user marked as not quittable cannot be stopped or replaced through the API. Do not blindly retry mutating calls.Reference at a glance
| Call | Name | What it does |
|---|---|---|
| execute | START_FOCUS / STOP_FOCUS | Start a session with a focus group ID and minutes or an exact end time; optional Pomodoro fields from v7 |
| execute | SAVE_FOCUS_GROUP / DELETE_FOCUS_GROUP | Create, update or remove focus groups (v7) |
| execute | SET_APP_BLOCKER_GROUP, SET_KEYWORD_GROUP, SET_GRAYSCALE_GROUP | Turn one existing group on or off |
| execute | SET_KEYWORD_BLOCKER, SET_REEL_BLOCKER, SET_UI_HIDER, SET_REEL_COUNTER | Global toggles; SET_UI_HIDER fails on Play Store builds |
| execute | SET_DND | Request Do Not Disturb on or off, if Curbox already has notification policy access |
| execute | HOST_COMPANION | Ask Curbox to keep your companion service running (v6) |
| query | FOCUS_ACTIVE, SCREENTIME_TODAY, REELS_TODAY | Current focus state, today's minutes, today's reel count |
| list | FOCUS_GROUPS, APP_BLOCKER_GROUPS, KEYWORD_GROUPS, … | Group IDs and names to target with commands |
| list | USAGE_HISTORY | Up to 28 days, newest first, with each day's top 25 apps and website domains (v5) |
| list | STATUS | One object with the stored toggles and focus state |
A USAGE_HISTORY item looks like this:
[{"date":"2026-11-03","screenTimeMs":5400000,"apps":[{"packageName":"com.example.social","label":"Social","ms":1800000,"launches":14}],"websites":[{"domain":"example.com","ms":600000}]}]
Rather than polling, register an ICurboxListener (version 6). Curbox calls onChanged("FOCUS") when a session starts, stops or changes phase, and onChanged("FOCUS_GROUPS") when a focus group's contents change.
Custom unlock requirements
This is the most interesting hook. Your app can register a named check, such as "At the library" or "Finish 20 cards", that users pick on a blocked group's pause screen under Require effort to unlock → Require another app. When the user tries to unlock, Curbox launches your activity for result, and your answer decides whether they get through. Curbox keeps control of the delay, unlock duration and proceed limits.
Kotlin · register a requirement (API 3+)
val status = withContext(Dispatchers.IO) {
remote.execute("REGISTER_UNLOCK_CONDITION", Bundle().apply {
putString("id", "daily_cards")
putString("label", "Finish 20 cards")
putString("activity", "com.example.practice.CheckRequirementActivity")
})
}
The check activity must live in your own package, be exported, and require no manifest permission. Each package can register up to 50 requirements, and a registered ID cannot be edited in place, so a requirement a user picked never silently changes meaning. A real example is Curbox's Location Blocker, an open source add-on that lets users unlock only at, or only away from, a saved place.
Security model
- Verified caller. The Binder UID decides who is calling. A client cannot impersonate another package by naming it in arguments.
- Pinned grants. Approval is tied to package and signing certificates.
- Protected approval screen. Only a verified Activity caller can open it, obscured touches are filtered, and non-system overlays are hidden on Android 12 and newer.
- Restriction rules hold. API changes use the same settings gates as the app, and protected focus sessions cannot be ended through the API.
- Trust still matters. Curbox cannot verify a provider's private data, and an approved app gets the full public API. Users should approve apps they trust.
The full guide, with binding lifecycle code, every argument, error handling and a bundled tester app (:apitester), is CURBOX_API.md on GitHub. Everything on this page is summarized from it (checked November 2026, API version 7). Code blocks are quoted from it unchanged.
App blocker API FAQ
Is there an app blocker API for Android?
Curbox exposes one. It is a local Android Binder service with an AIDL interface, currently at API version 7. An app the user approves can start and stop focus sessions, turn blocker groups on and off, read screen time and usage history, and register its own unlock requirements.
Is the Curbox API a web or HTTP API?
No. There is no HTTP server, web API, API key, OAuth flow or remote endpoint. Your code must run as an Android app on the same phone. A browser, server or desktop app needs an Android companion app to use it.
How does a user grant my app access?
Your Activity launches Curbox's REQUEST_PERMISSION activity for result, and the user approves your app there. Access is tied to your package and signing certificates. The user can revoke it under Reducers, Curbox API, Connected apps, and uninstalling your app ends the grant.
Can my app read screen time data?
Yes, once approved. You can query today's screen time in minutes and today's reel count, and list daily usage history for up to 28 days, including the top apps with launches and the top website domains for each day.
How is this different from Android's UsageStatsManager?
UsageStatsManager gives your app raw usage data after the user grants usage access in Settings, and you build everything else yourself. The Curbox API gives you an existing blocker to drive: focus sessions, blocker toggles, per-domain browser usage and reel counts, plus hooks into Curbox's pause screen.
Can my app create or edit blocking rules?
Only partly. From version 7 you can create, edit and delete focus groups, including their apps and websites. App blocker groups, schedules, limits and warning settings cannot be created or edited through the API; you can only turn existing groups on or off.