Skip to main content
PATCH
Update Agent Profile

Authorizations

X-Api-Key
string
header
required

Path Parameters

profileId
string<uuid>
required

The ID of the agent profile

Body

application/json

Fields to update

Request to update an existing agent profile

adblockActive
boolean

Whether to enable ad blocking

allow3rdCookies
boolean

Whether to allow third-party cookies

cachePersistence
boolean

Whether to persist browser cache between sessions

captchaSolverActive
boolean

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

cookiesToAdd
object[]

Cookies to add to the profile

cookiesToDelete
string<uuid>[]

IDs of cookies to remove from the profile

credentialsToAdd
object[]
deprecated

Deprecated: Use vaultItemIds instead. Credentials to add to the profile.

credentialsToDelete
string<uuid>[]
deprecated

Deprecated: Use vaultItemIds instead. IDs of credentials to remove from the profile.

credentialsToUpdate
object[]
deprecated

Deprecated: Use vaultItemIds instead. Credentials to update by name (matched case-insensitively).

customProxy
object

Custom proxy configuration (for custom proxy mode)

description
string

New description for the profile

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

Stable org extension IDs to attach to this profile

extraStealth
boolean

Whether to enable extra stealth mode

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

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

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

name
string

New name for the profile

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

Operating system to emulate

Available options:
macos,
windows
pdfViewerActive
boolean

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

popupBlockerActive
boolean

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

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)

proxyMode
enum<string>

Proxy configuration mode

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

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

Available options:
basic
tracingEnabled
boolean

Whether browser tracing is enabled (admin only)

vaultItemIds
string<uuid>[]

Org vault item IDs attached to this profile.

Response

The request has succeeded.

An agent profile containing browser configuration and credentials

adblockActive
boolean
required

Whether to enable ad blocking

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

List of cookies associated with this profile

createdAt
string<date-time>
required

When the profile was created

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

Description of the agent profile

extensionIds
string<uuid>[]
required

Stable org extension IDs attached to this profile

extraStealth
boolean
required

Whether extra stealth mode is enabled

forcePopupsAsTabsActive
boolean
required

Whether to force popups to open as tabs

id
string<uuid>
required

Unique identifier for the agent profile

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

When the profile was last updated

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

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