> ## Documentation Index > Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Profile > Create a new profile. 409 when two attached secrets share a key. ## OpenAPI ````yaml https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /profiles openapi: 3.1.0 info: title: Agent Service version: v1 servers: - description: V2 API url: https://odyssey.asteroid.ai/agents/v2 security: - ApiKeyAuth: [] tags: - name: Agents - name: Environments - name: Schedules - name: Execution - name: Files - name: Profiles - name: Profile Groups - name: Agent Profiles - name: Agent Profile Pools - name: Workflows - name: Execution Batches - name: Scheduled Executions - name: Schema - name: Documentation - name: Context - name: Admin Customer Activity - name: Reference - name: Workflow Tags - name: Secrets - name: Vault - name: Workflow Versions paths: /profiles: post: tags: - Profiles summary: Create Profile description: Create a new profile. 409 when two attached secrets share a key. operationId: ProfilesCreate requestBody: content: application/json: schema: $ref: '#/components/schemas/Agents.Profile.CreateAgentProfileRequest' description: Profile to create required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/Agents.Profile.AgentProfile' description: >- The request has succeeded and a new resource has been created as a result. '400': content: application/json: schema: $ref: '#/components/schemas/Common.BadRequestErrorBody' description: The server could not understand the request due to invalid syntax. '401': content: application/json: schema: $ref: '#/components/schemas/Common.UnauthorizedErrorBody' description: Access is unauthorized. '403': content: application/json: schema: $ref: '#/components/schemas/Common.ForbiddenErrorBody' description: Access is forbidden. '404': content: application/json: schema: $ref: '#/components/schemas/Common.NotFoundErrorBody' description: The server cannot find the requested resource. '409': content: application/json: schema: $ref: '#/components/schemas/Common.ConflictErrorBody' description: The request conflicts with the current state of the server. '500': content: application/json: schema: $ref: '#/components/schemas/Common.InternalServerErrorBody' description: Server error components: schemas: Agents.Profile.CreateAgentProfileRequest: description: Request to create a new agent profile properties: adblockActive: default: false description: Whether to enable ad blocking type: boolean allow3rdCookies: default: false description: Whether to allow third-party cookies type: boolean cachePersistence: default: false description: Whether to persist browser cache between sessions type: boolean captchaSolverActive: default: false description: Whether the captcha solver should be active (managed proxy only) type: boolean cookies: description: Initial cookies to create with the profile items: $ref: '#/components/schemas/Agents.Profile.Cookie' type: array credentials: deprecated: true description: >- Deprecated: Use vaultItemIds instead. Initial credentials to create with the profile. items: $ref: '#/components/schemas/Agents.Profile.Credential' type: array x-hidden: true customProxy: allOf: - $ref: '#/components/schemas/Agents.Profile.CustomProxyConfigInput' description: Custom proxy configuration (required for custom proxy mode) description: description: Description of the agent profile maxLength: 1000 type: string extensionIds: description: Stable org extension IDs to attach to this profile items: $ref: '#/components/schemas/Common.uuid' type: array extraStealth: default: false description: Whether to enable extra stealth mode type: boolean fingerprintId: anyOf: - $ref: '#/components/schemas/Agents.Profile.FingerprintIdInput' - type: 'null' description: >- 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. forcePopupsAsTabsActive: default: true description: Whether to force popups to open as tabs type: boolean inboxEmailPrefix: description: >- Optional custom prefix for the agent's inbox email address. If set, the inbox will be {prefix}@agentmail.asteroid.ai. type: string mediaBlockerActive: default: false description: Whether to enable media blocking (images, videos, etc.) type: boolean name: description: Name of the agent profile (must be unique within organization) maxLength: 255 minLength: 1 type: string operatingSystem: allOf: - $ref: '#/components/schemas/Agents.Profile.OperatingSystem' description: Operating system to emulate organizationId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The ID of the organization that the profile belongs to pdfViewerActive: default: false description: >- Whether to enable the built-in PDF viewer (if disabled, PDFs are downloaded) type: boolean popupBlockerActive: default: false description: Whether to enable popup blocking (requires adblock to be active) type: boolean proxyCC: allOf: - $ref: '#/components/schemas/Agents.Profile.CountryCode' description: Country code for proxy location (for managed proxy mode) proxyGatewayPresetId: allOf: - $ref: '#/components/schemas/Common.uuid' description: Proxy gateway preset ID (required for gateway proxy mode) proxyMode: allOf: - $ref: '#/components/schemas/Agents.Profile.ProxyMode' default: none description: Proxy configuration mode proxyType: allOf: - $ref: '#/components/schemas/Agents.Profile.ProxyType' description: Type of managed proxy to use (required for managed proxy mode) stickyIP: default: false description: >- Whether to use the same IP address for all executions (managed proxy only) type: boolean tracingEnabled: default: true description: Whether browser tracing is enabled (admin only, defaults to true) type: boolean vaultItemIds: description: Org vault item IDs attached to this profile. items: $ref: '#/components/schemas/Common.uuid' type: array required: - name - description - organizationId type: object Agents.Profile.AgentProfile: description: An agent profile containing browser configuration and credentials properties: adblockActive: description: Whether to enable ad blocking type: boolean allow3rdCookies: description: Whether to allow third-party cookies type: boolean cachePersistence: description: Whether to persist browser cache between sessions type: boolean captchaSolverActive: description: >- Whether the captcha solver is active for this profile (managed proxy only) type: boolean cookies: description: List of cookies associated with this profile items: $ref: '#/components/schemas/Agents.Profile.Cookie' type: array createdAt: description: When the profile was created format: date-time type: string credentials: deprecated: true description: >- Deprecated: Use vaultItems instead. Legacy credential names mirrored from attached vault items (legacyName). Prefer vaultItems; ##NAME## remains a grace-period alias. items: $ref: '#/components/schemas/Agents.Profile.Credential' type: array x-hidden: true customProxy: allOf: - $ref: '#/components/schemas/Agents.Profile.CustomProxyConfigOutput' description: >- Custom proxy configuration (for custom proxy mode, password excluded) description: description: Description of the agent profile type: string extensionIds: description: Stable org extension IDs attached to this profile items: $ref: '#/components/schemas/Common.uuid' type: array extraStealth: description: Whether extra stealth mode is enabled type: boolean fingerprintId: anyOf: - type: string - type: 'null' description: >- Anchor browser fingerprint ID applied at session create (admin only). Absent or null when unset. forcePopupsAsTabsActive: description: Whether to force popups to open as tabs type: boolean id: allOf: - $ref: '#/components/schemas/Common.uuid' description: Unique identifier for the agent profile inboxEmail: description: The resolved inbox email address for this profile type: string inboxEmailPrefix: description: >- 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. type: string mediaBlockerActive: description: Whether to enable media blocking (images, videos, etc.) type: boolean name: description: Name of the agent profile (unique within organization) type: string operatingSystem: allOf: - $ref: '#/components/schemas/Agents.Profile.OperatingSystem' description: Operating system to emulate organizationId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The ID of the organization that owns this profile pdfViewerActive: description: >- Whether to enable the built-in PDF viewer (if disabled, PDFs are downloaded) type: boolean popupBlockerActive: description: Whether to enable popup blocking (requires adblock to be active) type: boolean proxyCC: allOf: - $ref: '#/components/schemas/Agents.Profile.CountryCode' description: Country code for proxy location (for managed proxy mode) proxyGatewayPresetId: allOf: - $ref: '#/components/schemas/Common.uuid' description: Proxy gateway preset ID (for gateway proxy mode) proxyMode: allOf: - $ref: '#/components/schemas/Agents.Profile.ProxyMode' description: Proxy configuration mode proxyType: allOf: - $ref: '#/components/schemas/Agents.Profile.ProxyType' description: Type of managed proxy to use (for managed proxy mode) stickyIP: description: >- Whether to use the same IP address for all executions (managed proxy only) type: boolean tracingEnabled: description: Whether browser tracing is enabled (admin only) type: boolean updatedAt: description: When the profile was last updated format: date-time type: string vaultItems: description: Org vault items attached to this profile. Deleted items are omitted. items: $ref: '#/components/schemas/Agents.Profile.AgentProfileVaultItemRef' type: array required: - id - name - description - organizationId - proxyMode - captchaSolverActive - stickyIP - extraStealth - allow3rdCookies - cachePersistence - adblockActive - popupBlockerActive - forcePopupsAsTabsActive - mediaBlockerActive - pdfViewerActive - tracingEnabled - extensionIds - vaultItems - inboxEmail - credentials - cookies - createdAt - updatedAt type: object Common.BadRequestErrorBody: properties: code: enum: - 400 type: number x-enum-varnames: - BadRequest message: type: string required: - code - message type: object Common.UnauthorizedErrorBody: properties: code: enum: - 401 type: number x-enum-varnames: - Unauthorized message: type: string required: - code - message type: object Common.ForbiddenErrorBody: properties: code: enum: - 403 type: number x-enum-varnames: - Forbidden message: type: string required: - code - message type: object Common.NotFoundErrorBody: properties: code: enum: - 404 type: number x-enum-varnames: - NotFound message: type: string required: - code - message type: object Common.ConflictErrorBody: properties: code: enum: - 409 type: number x-enum-varnames: - Conflict message: type: string required: - code - message type: object Common.InternalServerErrorBody: properties: code: enum: - 500 type: number x-enum-varnames: - InternalServerError message: type: string required: - code - message type: object Agents.Profile.Cookie: description: A browser cookie stored for an agent profile properties: createdAt: description: When the cookie was created format: date-time type: string domain: description: The domain for which the cookie is valid minLength: 1 type: string expiry: description: When the cookie expires (optional) format: date-time type: string httpOnly: description: Whether the cookie should be accessible only via HTTP(S) type: boolean id: allOf: - $ref: '#/components/schemas/Common.uuid' description: Unique identifier for the cookie key: description: The cookie key/name as sent in HTTP headers minLength: 1 type: string name: description: Display name for the cookie minLength: 1 type: string sameSite: allOf: - $ref: '#/components/schemas/Agents.Profile.SameSite' description: SameSite attribute for the cookie secure: description: Whether the cookie should only be sent over HTTPS type: boolean value: description: The cookie value minLength: 1 type: string required: - name - key - value - domain - secure - sameSite - httpOnly type: object Agents.Profile.Credential: description: A credential stored for an agent profile properties: createdAt: description: When the credential was created format: date-time type: string data: description: The credential value (plaintext - will be encrypted server-side) minLength: 1 type: string id: allOf: - $ref: '#/components/schemas/Common.uuid' description: Unique identifier for the credential name: description: Display name for the credential (will be uppercased) minLength: 1 type: string required: - name - data type: object Agents.Profile.CustomProxyConfigInput: description: Custom proxy server configuration for input (includes password) properties: password: description: Proxy authentication password minLength: 1 type: string server: description: >- Proxy server address including protocol and port (e.g., 'socks5://proxy.example.com:1080' or 'http://proxy.example.com:8080') minLength: 1 type: string username: description: Proxy authentication username minLength: 1 type: string required: - server - username - password type: object Common.uuid: format: uuid type: string Agents.Profile.FingerprintIdInput: description: >- Anchor browser fingerprint ID (24-character hex). An empty string means unset (create) or clear (update). pattern: ^([a-fA-F0-9]{24})?$ type: string Agents.Profile.OperatingSystem: description: Operating system to emulate in the browser enum: - macos - windows type: string Agents.Profile.CountryCode: description: Two-letter country code for proxy location enum: - us - uk - fr - it - jp - au - de - fi - ca type: string Agents.Profile.ProxyMode: description: Proxy configuration mode enum: - none - managed - custom - gateway type: string Agents.Profile.ProxyType: description: Type of managed proxy to use for browser sessions enum: - basic type: string Agents.Profile.CustomProxyConfigOutput: description: Custom proxy server configuration for output (excludes password) properties: server: description: Proxy server address type: string username: description: Proxy authentication username type: string required: - server - username type: object Agents.Profile.AgentProfileVaultItemRef: description: >- Summary of an org vault item attached to an agent profile. Field values are not included. properties: fields: items: $ref: '#/components/schemas/Agents.Profile.AgentProfileVaultItemFieldRef' type: array id: $ref: '#/components/schemas/Common.uuid' itemKey: $ref: '#/components/schemas/Agents.Vault.ItemKey' kind: $ref: '#/components/schemas/Agents.Vault.ItemKind' name: type: string required: - id - itemKey - name - kind - fields type: object Agents.Profile.SameSite: description: SameSite attribute for cookies enum: - Strict - Lax - None type: string Agents.Profile.AgentProfileVaultItemFieldRef: description: A field on an attached vault item. Values are omitted. properties: key: $ref: '#/components/schemas/Agents.Vault.FieldKey' legacyPlaceholder: description: >- Legacy ##NAME## placeholder when this field was mirrored from an older profile credential. type: string placeholder: description: 'Canonical placeholder, e.g. ##MY_PORTAL.USERNAME##' type: string type: $ref: '#/components/schemas/Agents.Vault.FieldType' required: - key - type - placeholder type: object Agents.Vault.ItemKey: description: >- UPPER_SNAKE vault item key. Derived from name when omitted on create. Unique among a profile's attached items, not across the organisation. Stays the same across renames. maxLength: 64 minLength: 1 pattern: ^[A-Z0-9]+(?:_[A-Z0-9]+)*$ type: string Agents.Vault.ItemKind: description: >- Kind of vault item. Templates and items need at least one field. Completeness is per-field required. enum: - login - api_key - card - custom type: string x-enum-varnames: - VaultItemKindLogin - VaultItemKindApiKey - VaultItemKindCard - VaultItemKindCustom Agents.Vault.FieldKey: description: UPPER_SNAKE field key, unique within a template or item. maxLength: 64 minLength: 1 pattern: ^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$ type: string Agents.Vault.FieldType: description: >- Type of a vault field. Sensitivity is derived from the type: username, email, url, phone, text, card_expiry, and cardholder_name are readable; password, hidden, totp_seed, api_key, card_number, and card_cvv are write-only. There is no separate hidden flag. enum: - username - email - url - phone - text - password - hidden - totp_seed - api_key - card_number - card_expiry - card_cvv - cardholder_name type: string x-enum-varnames: - VaultFieldTypeUsername - VaultFieldTypeEmail - VaultFieldTypeUrl - VaultFieldTypePhone - VaultFieldTypeText - VaultFieldTypePassword - VaultFieldTypeHidden - VaultFieldTypeTotpSeed - VaultFieldTypeApiKey - VaultFieldTypeCardNumber - VaultFieldTypeCardExpiry - VaultFieldTypeCardCvv - VaultFieldTypeCardholderName securitySchemes: ApiKeyAuth: in: header name: X-Api-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.