Housekeeping REST API
Trash
Deleting is always reversible. Purged automatically 30 days after deletion.
List trashed items
GET/api/v1/trash
Deleted profiles and projects, newest deletion first, each with how long it has left.
Returns
{ total, items: TrashEntry[] }
Restore a profile
POST/api/v1/trash/profiles/:id/restore
Brings a profile back with its browser data untouched.
Path parameters
| Field | Type | What it is |
|---|---|---|
idrequired | string | The record’s id. |
Returns
The restored Profile.
Purge a profile
DELETE/api/v1/trash/profiles/:id
Permanent. Removes the profile and its browser data directory from disk.
Path parameters
| Field | Type | What it is |
|---|---|---|
idrequired | string | The record’s id. |
Returns
{ purged: true }
Restore a project
POST/api/v1/trash/projects/:id/restore
Restores the project and every profile deleted along with it.
Path parameters
| Field | Type | What it is |
|---|---|---|
idrequired | string | The record’s id. |
Returns
The restored Project.
Purge a project
DELETE/api/v1/trash/projects/:id
Permanent, including every profile inside it.
Path parameters
| Field | Type | What it is |
|---|---|---|
idrequired | string | The record’s id. |
Returns
{ purged: true }
Restore a warm-up plan
POST/api/v1/trash/warmup/plans/:id/restore
Brings a trashed plan back. DELETE /warmup/plans/:id trashes rather than destroys — a plan is a list of sites somebody assembled by hand, and it takes longer to rebuild than to lose.
Path parameters
| Field | Type | What it is |
|---|---|---|
idrequired | string | The record’s id. |
Returns
The restored WarmupPlan.
Purge a warm-up plan
DELETE/api/v1/trash/warmup/plans/:id
Permanent. By id only — there is no purge-everything for plans.
Path parameters
| Field | Type | What it is |
|---|---|---|
idrequired | string | The record’s id. |
Returns
{ purged: true }
Empty the trash
POST/api/v1/trash/empty
Permanent, and the only call here that destroys more than one thing at a time — every profile it removes takes its cookies, logins and browsing history with it, and there is nothing to restore from. It will not guess how much you meant: an empty body is a 400, not a full purge. Name a projectId, name an os list, or send { "all": true } to mean every row. That default cost 586 profiles once — a script that meant "tidy up the one fixture I made" sent no body and purged a library — and on the single irreversible route in this API, absent must not mean maximal. A platform filter deliberately spares trashed projects: a project is not in a platform, and purging one because a caller named android would take desktop profiles nobody asked about. An unknown field is a 400 rather than a silently wider purge.
Body
| Field | Type | What it is |
|---|---|---|
projectId | string | Only this project’s trash. |
os | "windows" | "macos" | "linux" | "android"[] | Only these platforms’ profiles, and no projects. |
all | boolean | Every row, with nothing spared. Cannot be combined with the other two. |
Returns
{ purged: n } — how many profiles and projects were removed.
Errors
- 400 — no scope at all. Say
projectId,osorall. - 400 —
allcombined withprojectIdoros. - 400 — an unknown field, or an
osentry that is not a platform.
curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"projectId":"'$PROJECT'","os":["android"]}' "$BASE/trash/empty"Run the API on your own profiles
The REST API and the MCP server are part of Pro: $49 a month, with the first 14 days free. Free has every browser feature and no API key.
Mosaic is a desktop app
Email yourself the link and open it on your computer.