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

/profile/refresh

POST 

/profile/refresh

Replaces the state of an existing authentication profile in place. The "name" must already exist for the requesting token. Counts of any dropped or truncated entries are surfaced under "diagnostics".

Request​

Body

    namestringrequired

    Name of the existing profile to refresh. Must already exist for the requesting token.

    staterequired

    Pre-captured authentication state. Same shape as POST /profile/upload.

    captureSettings object

    Capture inputs this refresh ran with. Omit the key to leave the stored settings untouched — which is what an older CLI does. An object that survives validation REPLACES the stored one wholesale — it is not a patch, so a partial payload drops the members it omits.

    An object that validates down to nothing — {}, or one carrying only onlyDomains: [] / keepDomains: [] — is treated as if the key were omitted: 200, stored settings untouched. excludeDomains: [] is the deliberate exception: it survives, so the payload DOES replace the stored object and drops every member it omits. It 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 refresh.

    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?