For AI agents: a documentation index is available at /llms.txt
Skip to main content

/profile/upload

POST 

/profile/upload

Creates a new authentication profile from a pre-captured "state" payload (cookies plus per-origin localStorage and IndexedDB). The "name" must be unique per token. Counts of any dropped or truncated entries are surfaced under "diagnostics".

Request​

Body

    namestringrequired

    A user-visible name for the profile. Must be unique per token.

    staterequired

    Pre-captured authentication state. An object with two arrays — cookies (browser cookies) and origins (per-origin localStorage and IndexedDB).

    captureSettings object

    Capture inputs the CLI ran with, stored so a later browserless profile refresh can replay them without flags. Optional — an older CLI omits it. This route is a strict create, so there is nothing to preserve: the profile is created with these settings, or with none.

    An object that validates down to nothing — {}, or one carrying only onlyDomains: [] / keepDomains: [] — is stored as null, the same as omitting the key. excludeDomains: [] is the deliberate exception: it survives and records "captured with no exclusions", which a later flagless refresh replays instead of re-reading the refreshing machine's own config.

    browserstring

    Raw --browser value.

    profilestring

    Raw --profile value.

    excludeDomainsstring[]

    Effective merged exclusion list, not just the --exclude-domain flags.

    onlyDomainsstring[]

    Normalized --only-domain hostnames, deduped and capped — not merged with local config.

    keepDomainsstring[]

    Normalized --keep-domain hostnames, same normalization, no merge.

    autoFitboolean

    Whether --auto-fit was used.

    passwordStorestring

    Raw --password-store value. Linux only.

    cliVersionstring

    CLI version that produced these settings.

Responses​

Schema
    diagnostics objectrequired

    Per-entry counts of cookies, origins, and IndexedDB items the server dropped or truncated before persisting. All zero on a clean upload.

    skippedMalformedCookiesnumberrequired

    Cookies dropped because required fields were missing or wrong type.

    skippedPrivateCookiesnumberrequired

    Cookies dropped because their domain pointed at a private/internal host.

    skippedMalformedOriginsnumberrequired

    Origins dropped because they were malformed or non-http(s).

    skippedPrivateOriginsnumberrequired

    Origins dropped because they targeted a private/internal network.

    truncatedOriginsnumberrequired

    Origins dropped because the per-profile cap was exceeded.

    skippedMalformedIdbDatabasesnumberrequired

    IndexedDB databases dropped because required fields were missing.

    truncatedIdbDatabasesnumberrequired

    IndexedDB databases dropped because the per-origin cap was exceeded.

    skippedMalformedIdbStoresnumberrequired

    IndexedDB object-stores dropped because required fields were missing.

    truncatedIdbEntriesnumberrequired

    IndexedDB entries dropped because the per-store cap was exceeded.

    skippedMalformedLocalStorageEntriesnumberrequired

    localStorage entries dropped because names or values were not strings.

    skippedMalformedIdbIndexesnumberrequired

    IndexedDB indexes dropped because required fields were malformed.

    idstringrequired

    Unique profile identifier.

    namestringrequired

    User-supplied profile name. Unique per token.

    cookieCountnumberrequired

    Number of cookies captured in the profile.

    originCountnumberrequired

    Number of distinct origins with stored localStorage or IndexedDB.

    captureSettings objectrequired

    Capture inputs the CLI used, or null for profiles not created by the CLI. The UI derives no capture flag from these; it uses any non-empty object to stamp the CLI badge and show a read-only summary, and reads browser/profile specifically to decide whether its refresh command needs placeholders for them. The CLI reads the rest itself and decides the exclusion behaviour from excludeDomains.

    browserstring

    Raw --browser value.

    profilestring

    Raw --profile value (source profile directory or display name).

    excludeDomainsstring[]

    Effective merged exclusion list. [] is meaningful — "captured with no exclusions" — and distinct from absent, which means "unknown".

    onlyDomainsstring[]

    Normalized --only-domain hostnames, deduped and capped — not merged with local config.

    keepDomainsstring[]

    Normalized --keep-domain hostnames, same normalization, no merge.

    autoFitboolean

    Whether --auto-fit was used.

    passwordStorestring

    Raw --password-store value. Linux only.

    cliVersionstring

    CLI version that produced these settings, for drift diagnosis.

    domainAuth object[]required

    Per-domain auth status + expiry for the saved logins in this profile, with status classified at read time (valid / expiring_soon / expired / unknown). Empty for profiles saved before this feature, until their next capture, upload, or refresh. Never contains a cookie value.

  • Array [
  • domainstringrequired
    statusDomainAuthStatusrequired

    Per-domain auth status, computed at read time from a stored absolute expiry.

    Possible values: [expired, expiring_soon, unknown, valid]

    expiresAtstringrequired
  • ]
  • lastUsedAtstringrequired

    ISO timestamp of the last time this profile was applied to a session, or null if never used.

    createdAtstringrequired

    ISO timestamp of when the profile was created.

    updatedAtstringrequired

    ISO timestamp of the last metadata change (e.g., rename).

Was this page helpful?