Skip to main content
POST
Create Profile

Authorizations

X-Api-Key
string
header
required

Body

application/json

Request to create a new agent profile

description
string
required
Maximum string length: 1000
name
string
required

Name of the agent profile (must be unique within organization)

Required string length: 1 - 255
adblockActive
boolean
default:false
deprecated
allow3rdCookies
boolean
default:false
deprecated

Whether to allow third-party cookies

cachePersistence
boolean
default:false
deprecated

Whether to persist browser cache between sessions

captchaSolverActive
boolean
default:false
deprecated

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

cookies
object[]
deprecated
credentials
object[]
deprecated

Deprecated: use secretIds. Initial credentials to create with the profile.

customProxy
object
deprecated

Custom proxy configuration (required for custom proxy mode)

extensionIds
string<uuid>[]
deprecated

Stable org extension IDs to attach to this profile

extraStealth
boolean
default:false
deprecated
fingerprintId
string | null

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. Empty or null means unset.

Pattern: ^([a-fA-F0-9]{24})?$
forcePopupsAsTabsActive
boolean
default:true
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
default:false
deprecated

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

operatingSystem
enum<string>
deprecated

Operating system to emulate in the browser

Available options:
macos,
windows
organizationId
string<uuid>

The ID of the organization that the profile belongs to. Defaults to the one organization the caller acts in, such as an API key's. Required when the caller belongs to several.

pdfViewerActive
boolean
default:false
deprecated

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

popupBlockerActive
boolean
default:false
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 (required for gateway proxy mode)

proxyMode
enum<string>
default:none
deprecated

Proxy configuration mode

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

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

Available options:
basic
secretIds
string<uuid>[]

Secret IDs to attach to this profile. Do not set together with vaultItemIds.

stickyIP
boolean
default:false
deprecated

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

tracingEnabled
boolean
default:true

Whether browser tracing is enabled (admin only, defaults to true)

vaultItemIds
string<uuid>[]
deprecated

Deprecated: use secretIds. Org vault item IDs attached to this profile.

Response

The request has succeeded and a new resource has been created as a result.

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