# Cookies: Mosaic API reference

> Cookies in Mosaic’s local REST API: 3 routes, each with its method, path, fields, what it returns and the errors it names.

Source: https://mosaicbrowser.com/docs/api/cookies

**A profile’s data** REST API

## Cookies

Written through DevTools, so Chromium performs its own encoding and encryption.

- [GETRead a profile’s cookies](#get-cookies)
- [POSTImport cookies](#set-cookies)
- [DELETEClear stored cookies](#clear-cookies)

## [Read a profile’s cookies](#get-cookies)

GET`/api/v1/profiles/:id/cookies`

The profile’s actual cookie jar, whether or not it is running. Over CDP while the browser is up, because the browser owns the file and has the newest writes; read straight out of Chromium’s SQLite database and decrypted when it is not. `source` says which of the two answered, so a jar that is genuinely empty can be told apart from one that could not be read. This used to return the live jar when running and the list somebody *imported* when stopped — two different facts behind one URL, and the stopped answer was silently wrong: a profile whose jar held a cookie answered `total: 0`.

#### Path parameters

| Field | Type | What it is |
| --- | --- | --- |
| `id`required | `string` | The record’s id. |

#### Returns

`{ total, source: "live" | "jar", cookies: CookieRecord[] }`

## [Import cookies](#set-cookies)

POST`/api/v1/profiles/:id/cookies`

Accepts every shape people actually have: a Cookie-Editor or EditThisCookie JSON array, a `{cookies:[…]}` wrapper, a Netscape `cookies.txt` — tab- or space-separated, including the `#HttpOnly_` prefix that curl and wget write and that a naive parser drops as a comment — or the bare `name=value; name2=value2` string copied out of a request header. Send it as `text` to be parsed, or as an already-parsed `cookies` array. A pasted header carries no domain, so `domain` supplies one; without it the import would set nothing and still report success. A running profile receives them immediately; a stopped one gets them at next launch. Because they go in through DevTools, an imported cookie is indistinguishable from one the profile earned by logging in.

**An imported cookie is applied once, and after that only when it changes.** The import replaces the profile’s imported list, and Mosaic keeps a digest of each cookie it last wrote into the browser (by domain, path and name). The next launch — or the running browser, now — receives only the cookies that are new or whose value or attributes differ; every other one is left to the browser, which by then holds the site’s own, newer copy. Re-importing the same export changes nothing, and a session token the site has rotated since is never rolled back to the imported one. Clearing a profile’s cookies forgets the digests too, so importing the same cookies afterwards applies them again. A body with neither `text` nor `cookies` is a `400`; a paste that reads as no cookies leaves the profile as it was and says why in `errors`.

#### Path parameters

| Field | Type | What it is |
| --- | --- | --- |
| `id`required | `string` | The record’s id. |

#### Body

| Field | Type | What it is |
| --- | --- | --- |
| `text` | `string` | Raw cookie text in any supported format. |
| `cookies` | `CookieRecord[]` | Pre-parsed cookies, used instead of `text` — the shape `GET` returns, extra CDP fields included. A record without a `name` or `domain` is a `400` naming its index. |
| `domain` | `string` | Required only for a pasted `Cookie:` header. |

#### Returns

`{ imported, applied, pending, unchanged, errors: string[], liveError: string | null }` — `applied` were written into the running browser now, `pending` wait for its next launch, `unchanged` were already there exactly and were left alone. `liveError` says why a running browser did not take them; they stay pending.

## [Clear stored cookies](#clear-cookies)

DELETE`/api/v1/profiles/:id/cookies`

Empties the profile’s stored cookie set and deletes the browser’s own cookie database, so a profile that has actually been used really does come back empty. Refused while the profile is running, because the browser would write its cookies straight back on exit.

#### Path parameters

| Field | Type | What it is |
| --- | --- | --- |
| `id`required | `string` | The record’s id. |

#### Returns

`{ cleared: 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.