Profiles REST API
Projects and tags
The two axes profiles are organised on: one project each, any number of tags.
List projects
GET/api/v1/projects
Every project with its profile count.
Returns
{ total, projects: Project[] } — each with profileCount (every profile in the project) and mobileProfileCount (the Android ones among them). Exactly one carries system: true; see PATCH /projects/:id for what that fixes.
Create a project
POST/api/v1/projects
A project is a workspace with its own profiles, proxies and extensions. Its colour and icon are what appear on the Dock icon of every profile launched from it.
Body
| Field | Type | What it is |
|---|---|---|
namerequired | string | Display name. |
icon | string | Icon id from the built-in set, e.g. "rocket". |
color | string | Hex colour. |
Returns
The created Project.
Read one project
GET/api/v1/projects/:id
One project with its profile count.
Path parameters
| Field | Type | What it is |
|---|---|---|
idrequired | string | The record’s id. |
Returns
A Project.
Errors
- 404 — no such project.
Update a project
PATCH/api/v1/projects/:id
Rename, recolour or change the icon. Changing colour or icon changes the Dock icon of its profiles on their next launch. One project refuses all three. Exactly one project carries system: true — the one Mosaic created at first launch, where every profile lands before anybody files it. It wears the Mosaic mark on white and its name, icon and color are fixed, so that what every other surface calls it stays true; sending any of them is a 400 naming the field, never a silent no-op. sortOrder is still yours: where it sits in the list changes nothing about what it is.
Path parameters
| Field | Type | What it is |
|---|---|---|
idrequired | string | The record’s id. |
Body
Partial<Project>. name, icon, color, sortOrder.
Returns
The updated Project.
Errors
400—name,iconorcoloron thesystemproject.
Move a project to the trash
DELETE/api/v1/projects/:id
Takes its profiles with it. Everything stays restorable for 30 days. Refused for the last remaining project, and for the system project — nothing re-creates that one, so deleting it would quietly end the concept for this installation. Every browser open in the project is closed first, and one that will not close keeps the whole project.
Path parameters
| Field | Type | What it is |
|---|---|---|
idrequired | string | The record’s id. |
Returns
{ deleted: true, stopped } — stopped counts the browsers closed on the way.
Errors
400— the last project, thesystemproject, or a browser that would not close.
List tags
GET/api/v1/tags
Tags defined in a project.
Query parameters
| Field | Type | What it is |
|---|---|---|
projectId | string | Restrict to one project. |
Returns
{ total, tags: Tag[] }
Create a tag
POST/api/v1/tags
Tags are a secondary axis within a project, and carry a colour used throughout the interface.
Body
| Field | Type | What it is |
|---|---|---|
namerequired | string | Tag name. |
color | string | Hex colour. |
projectId | string | Owning project. |
Returns
The created Tag.
Update a tag
PATCH/api/v1/tags/:id
Rename a tag or change its colour. A rename reaches every profile carrying it, because profiles store tags by name — this is the only correct way to change one. Renaming onto a name that already exists in the same project is a 400 rather than a merge: two tags with one name would both match the same filter, and merging them is a bigger decision than a rename. Any field other than name and color is a 400, so a misspelled key cannot be a 200 that changed nothing.
Path parameters
| Field | Type | What it is |
|---|---|---|
idrequired | string | The record’s id. |
Body
| Field | Type | What it is |
|---|---|---|
name | string | The new name. Renames it on every profile that carries it. |
color | string | A hex colour like #2b7fbd. Anything else is a 400 — a colour the browser cannot parse renders as no colour at all. |
Returns
The updated Tag.
Errors
- 400 — an unknown field, an empty name, a colour that is not
#rrggbb, or a name another tag in the project already has. - 404 — no tag with that id.
Delete a tag
DELETE/api/v1/tags/:id
Removes it from every profile that carries it.
Path parameters
| Field | Type | What it is |
|---|---|---|
idrequired | string | The record’s id. |
Returns
{ deleted: true }
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.