> ## 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 /agents/v2/profiles openapi: 3.1.0 info: title: Agent Service version: v1 servers: - url: https://odyssey.asteroid.ai 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: Insights - name: Workflow Versions paths: /agents/v2/profiles: post: tags: - Profiles summary: Create Profile description: Create a new profile. 409 when two attached secrets share a key. operationId: Profiles_create requestBody: content: application/json: schema: $ref: '#/components/schemas/Agents.Profile.CreateAgentProfileRequest' 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 deprecated: true type: boolean x-hidden: true allow3rdCookies: default: false deprecated: true description: Whether to allow third-party cookies type: boolean x-hidden: true cachePersistence: default: false deprecated: true description: Whether to persist browser cache between sessions type: boolean x-hidden: true captchaSolverActive: default: false deprecated: true description: Whether the captcha solver should be active (managed proxy only) type: boolean x-hidden: true cookies: deprecated: true items: $ref: '#/components/schemas/Agents.Profile.Cookie' type: array x-hidden: true credentials: deprecated: true description: >- Deprecated: use secretIds. 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' deprecated: true description: Custom proxy configuration (required for custom proxy mode) x-hidden: true description: maxLength: 1000 type: string extensionIds: deprecated: true description: Stable org extension IDs to attach to this profile items: $ref: '#/components/schemas/Common.uuid' type: array x-hidden: true extraStealth: default: false deprecated: true type: boolean x-hidden: true 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 deprecated: true description: Whether to force popups to open as tabs type: boolean x-hidden: true 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 deprecated: true description: Whether to enable media blocking (images, videos, etc.) type: boolean x-hidden: true 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' deprecated: true x-hidden: true organizationId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- 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: default: false deprecated: true description: >- Whether to enable the built-in PDF viewer (if disabled, PDFs are downloaded) type: boolean x-hidden: true popupBlockerActive: default: false deprecated: true description: Whether to enable popup blocking (requires adblock to be active) type: boolean x-hidden: true proxyCC: allOf: - $ref: '#/components/schemas/Agents.Profile.CountryCode' deprecated: true description: Country code for proxy location (for managed proxy mode) x-hidden: true proxyGatewayPresetId: allOf: - $ref: '#/components/schemas/Common.uuid' deprecated: true description: Proxy gateway preset ID (required for gateway proxy mode) x-hidden: true proxyMode: allOf: - $ref: '#/components/schemas/Agents.Profile.ProxyMode' default: none deprecated: true x-hidden: true proxyType: allOf: - $ref: '#/components/schemas/Agents.Profile.ProxyType' deprecated: true description: Type of managed proxy to use (required for managed proxy mode) x-hidden: true secretIds: description: >- Secret IDs to attach to this profile. Do not set together with vaultItemIds. items: $ref: '#/components/schemas/Common.uuid' type: array stickyIP: default: false deprecated: true description: >- Whether to use the same IP address for all executions (managed proxy only) type: boolean x-hidden: true tracingEnabled: default: true description: Whether browser tracing is enabled (admin only, defaults to true) type: boolean vaultItemIds: deprecated: true description: >- Deprecated: use secretIds. Org vault item IDs attached to this profile. items: $ref: '#/components/schemas/Common.uuid' type: array x-hidden: true required: - name - description type: object Agents.Profile.AgentProfile: description: An agent profile containing browser configuration and credentials properties: adblockActive: 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: items: $ref: '#/components/schemas/Agents.Profile.Cookie' type: array createdAt: 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: type: string extensionIds: description: Stable org extension IDs attached to this profile items: $ref: '#/components/schemas/Common.uuid' type: array extraStealth: 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: $ref: '#/components/schemas/Common.uuid' 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: $ref: '#/components/schemas/Agents.Profile.OperatingSystem' 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: $ref: '#/components/schemas/Agents.Profile.ProxyMode' 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: 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 detail: description: Explanation of this occurrence. Same text as message type: string errors: description: The parameters that failed validation, when known items: $ref: '#/components/schemas/Common.FieldError' type: array instance: description: The request path that produced the problem type: string message: type: string status: format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.UnauthorizedErrorBody: properties: code: enum: - 401 type: number x-enum-varnames: - Unauthorized detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.ForbiddenErrorBody: properties: capability: description: The missing capability key, when reason is capability_required type: string code: enum: - 403 type: number x-enum-varnames: - Forbidden detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string reason: allOf: - $ref: '#/components/schemas/Common.ForbiddenReason' description: Why the request was refused, when the client can act on it status: format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.NotFoundErrorBody: properties: code: enum: - 404 type: number x-enum-varnames: - NotFound detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.ConflictErrorBody: properties: code: enum: - 409 type: number x-enum-varnames: - Conflict detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Common.InternalServerErrorBody: properties: code: enum: - 500 type: number x-enum-varnames: - InternalServerError detail: description: Explanation of this occurrence. Same text as message type: string instance: description: The request path that produced the problem type: string message: type: string status: format: int32 type: integer title: description: Short summary of the problem type type: string type: description: >- A URI that identifies the problem type. about:blank when the status says it all type: string required: - code - message type: object Agents.Profile.Cookie: description: A browser cookie stored for an agent profile properties: createdAt: format: date-time type: string domain: minLength: 1 type: string expiry: format: date-time type: string httpOnly: description: Whether the cookie should be accessible only via HTTP(S) type: boolean id: $ref: '#/components/schemas/Common.uuid' key: description: The cookie key/name as sent in HTTP headers minLength: 1 type: string name: minLength: 1 type: string sameSite: $ref: '#/components/schemas/Agents.Profile.SameSite' secure: description: Whether the cookie should only be sent over HTTPS type: boolean 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: format: date-time type: string data: description: The credential value (plaintext - will be encrypted server-side) minLength: 1 type: string id: $ref: '#/components/schemas/Common.uuid' 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: 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: 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: type: string 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 Common.FieldError: description: A problem with one request parameter properties: detail: description: What is wrong with it type: string parameter: description: The query or path parameter name type: string required: - parameter - detail type: object Common.ForbiddenReason: enum: - capability_required type: string 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.