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
cookies
object[]
deprecated
credentials
object[]
deprecated

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

fingerprintId
string | null

Anchor browser fingerprint ID to apply at session create (admin only). Ignored unless the environment runs with extra stealth and an active proxy without sticky IP. Empty or null means unset.

Pattern: ^([a-fA-F0-9]{24})?$
inboxEmailPrefix
string

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

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.

secretIds
string<uuid>[]

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

stickyIP
boolean
default:false

Give browser runs on this profile one dedicated IP. Applies when the environment uses the managed proxy or no proxy.

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: who an agent signs in as. Credentials, cookies and an inbox. The environment it runs on is the workflow's choice.

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
id
string<uuid>
required
inboxEmail
string
required

The resolved inbox email address for this profile

name
string
required

Name of the agent profile (unique within organization)

organizationId
string<uuid>
required

The ID of the organization that owns this profile

stickyIP
boolean
required

Whether browser runs on this profile egress from one dedicated IP. Applies when the environment uses the managed proxy or no proxy.

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.

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.