Skip to main content
PATCH
Update Profile

Authorizations

X-Api-Key
string
header
required

Path Parameters

profileId
string<uuid>
required

Body

application/json

Request to update an existing agent profile

adblockActive
boolean
deprecated
allow3rdCookies
boolean
deprecated

Whether to allow third-party cookies

cachePersistence
boolean
deprecated

Whether to persist browser cache between sessions

captchaSolverActive
boolean
deprecated

Whether the captcha solver should be active (managed proxy only)

cookiesToAdd
object[]
deprecated
cookiesToDelete
string<uuid>[]
deprecated
credentialsToAdd
object[]
deprecated

Deprecated: use secretIds. Credentials to add to the profile.

credentialsToDelete
string<uuid>[]
deprecated

Deprecated: use secretIds. IDs of credentials to remove from the profile.

credentialsToUpdate
object[]
deprecated

Deprecated: use secretIds. Credentials to update by name (matched case-insensitively).

customProxy
object
deprecated

Custom proxy configuration (for custom proxy mode)

description
string
Maximum string length: 1000
extensionIds
string<uuid>[]
deprecated

Stable org extension IDs to attach to this profile

extraStealth
boolean
deprecated
fingerprintId
string

Anchor browser fingerprint ID to apply at session create (admin only). Ignored unless the browser runs with extra stealth and an active proxy without sticky IP, usually set on the custom environment. An empty string clears it; omit to leave unchanged. Null is rejected — the generated servers cannot tell null from an omitted field, so accepting it would turn an intended clear into a silent no-op.

Pattern: ^([a-fA-F0-9]{24})?$
forcePopupsAsTabsActive
boolean
deprecated

Whether to force popups to open as tabs

inboxEmailPrefix
string

Optional custom prefix for the agent's inbox email address. If set, the inbox will be {prefix}@agentmail.asteroid.ai.

mediaBlockerActive
boolean
deprecated

Whether to enable media blocking (images, videos, etc.)

name
string
Required string length: 1 - 255
operatingSystem
enum<string>
deprecated

Operating system to emulate in the browser

Available options:
macos,
windows
pdfViewerActive
boolean
deprecated

Whether to enable the built-in PDF viewer (if disabled, PDFs are downloaded)

popupBlockerActive
boolean
deprecated

Whether to enable popup blocking (requires adblock to be active)

proxyCC
enum<string>
deprecated

Country code for proxy location (for managed proxy mode)

Available options:
us,
uk,
fr,
it,
jp,
au,
de,
fi,
ca
proxyGatewayPresetId
string<uuid>
deprecated

Proxy gateway preset ID (for gateway proxy mode)

proxyMode
enum<string>
deprecated

Proxy configuration mode

Available options:
none,
managed,
custom,
gateway
proxyType
enum<string>
deprecated

Type of managed proxy to use (for managed proxy mode)

Available options:
basic
secretIds
string<uuid>[]

Secret IDs attached to this profile. Replaces the full list. To change part of it, use secretIdsToAdd and secretIdsToRemove.

secretIdsToAdd
string<uuid>[]

Secret IDs to attach. Secrets already attached stay. Cannot be combined with secretIds.

secretIdsToRemove
string<uuid>[]

Secret IDs to detach. IDs that are not attached are ignored. Applied before secretIdsToAdd. Cannot be combined with secretIds.

tracingEnabled
boolean

Whether browser tracing is enabled (admin only)

vaultItemIds
string<uuid>[]
deprecated

Deprecated: use secretIds.

vaultItemIdsToAdd
string<uuid>[]
deprecated

Deprecated: use secretIdsToAdd.

vaultItemIdsToRemove
string<uuid>[]
deprecated

Deprecated: use secretIdsToRemove.

Response

The request has succeeded.

An agent profile containing browser configuration and credentials

adblockActive
boolean
required
allow3rdCookies
boolean
required

Whether to allow third-party cookies

cachePersistence
boolean
required

Whether to persist browser cache between sessions

captchaSolverActive
boolean
required

Whether the captcha solver is active for this profile (managed proxy only)

cookies
object[]
required
createdAt
string<date-time>
required
credentials
object[]
required
deprecated

Deprecated: Use vaultItems instead. Legacy credential names mirrored from attached vault items (legacyName). Prefer vaultItems; ##NAME## remains a grace-period alias.

description
string
required
extensionIds
string<uuid>[]
required

Stable org extension IDs attached to this profile

extraStealth
boolean
required
forcePopupsAsTabsActive
boolean
required

Whether to force popups to open as tabs

id
string<uuid>
required
inboxEmail
string
required

The resolved inbox email address for this profile

mediaBlockerActive
boolean
required

Whether to enable media blocking (images, videos, etc.)

name
string
required

Name of the agent profile (unique within organization)

organizationId
string<uuid>
required

The ID of the organization that owns this profile

pdfViewerActive
boolean
required

Whether to enable the built-in PDF viewer (if disabled, PDFs are downloaded)

popupBlockerActive
boolean
required

Whether to enable popup blocking (requires adblock to be active)

proxyMode
enum<string>
required

Proxy configuration mode

Available options:
none,
managed,
custom,
gateway
stickyIP
boolean
required

Whether to use the same IP address for all executions (managed proxy only)

tracingEnabled
boolean
required

Whether browser tracing is enabled (admin only)

updatedAt
string<date-time>
required
vaultItems
object[]
required

Org vault items attached to this profile. Deleted items are omitted.

customProxy
object

Custom proxy configuration (for custom proxy mode, password excluded)

fingerprintId
string | null

Anchor browser fingerprint ID applied at session create (admin only). Absent or null when unset.

inboxEmailPrefix
string

Optional custom prefix for the agent's inbox email address. If set, the inbox will be {prefix}@agentmail.asteroid.ai. If not set, defaults to the first 8 characters of the profile ID.

operatingSystem
enum<string>

Operating system to emulate in the browser

Available options:
macos,
windows
proxyCC
enum<string>

Country code for proxy location (for managed proxy mode)

Available options:
us,
uk,
fr,
it,
jp,
au,
de,
fi,
ca
proxyGatewayPresetId
string<uuid>

Proxy gateway preset ID (for gateway proxy mode)

proxyType
enum<string>

Type of managed proxy to use (for managed proxy mode)

Available options:
basic