> ## 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: API Keys
  - name: Integrations
  - name: Billing
  - name: Proxy Gateways
  - name: Admin Customer Activity
  - name: Reference
  - name: Workflow Tags
  - name: Secrets
  - name: Vault
  - name: Catalog
  - name: Chats
  - name: Insights
  - name: Portal Skills
  - name: Skills
  - name: Memory
  - name: Workflow Versions
  - name: Support
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:
        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
        description:
          maxLength: 1000
          type: string
        fingerprintId:
          anyOf:
            - $ref: '#/components/schemas/Agents.Profile.FingerprintIdInput'
            - type: 'null'
          description: >-
            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.
        inboxEmailPrefix:
          description: >-
            Optional custom prefix for the email inbox address. If set, the
            inbox will be {prefix}@agentmail.asteroid.ai.
          type: string
        name:
          description: Name of the agent profile (must be unique within organization)
          maxLength: 255
          minLength: 1
          type: string
        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.
        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
          description: >-
            Give browser runs on this profile one dedicated IP. Applies when the
            environment uses no proxy or the default managed proxy. Any other
            proxy, or a gateway, turns it off.
          type: boolean
        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: who an agent signs in as. Credentials, cookies and an
        inbox. The environment it runs on is the workflow's choice.
      properties:
        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
        description:
          type: string
        fingerprintId:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Browser fingerprint ID applied at session create (admin only).
            Absent or null when unset.
        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 email inbox 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
        name:
          description: Name of the agent profile (unique within organization)
          type: string
        organizationId:
          allOf:
            - $ref: '#/components/schemas/Common.uuid'
          description: The ID of the organization that owns this profile
        stickyIP:
          description: >-
            Whether browser runs on this profile egress from one dedicated IP.
            Applies when the environment uses no proxy or the default managed
            proxy. Any other proxy, or a gateway, turns it off.
          type: boolean
        stickyIPHistory:
          description: >-
            IP addresses observed on browser runs that used this profile's
            sticky IP, newest first. The first entry is the current address.
            Empty until a run boots after the profile's first saved session.
          items:
            $ref: '#/components/schemas/Agents.Profile.AgentProfileObservedIP'
          type: array
        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
        - tracingEnabled
        - stickyIP
        - stickyIPHistory
        - 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.FingerprintIdInput:
      description: >-
        Browser fingerprint ID (24-character hex). An empty string means unset
        (create) or clear (update).
      pattern: ^([a-fA-F0-9]{24})?$
      type: string
    Common.uuid:
      format: uuid
      type: string
    Agents.Profile.AgentProfileObservedIP:
      description: An IP address observed on a browser run, and when it first appeared.
      properties:
        firstSeenAt:
          format: date-time
          type: string
        ip:
          type: string
      required:
        - ip
        - firstSeenAt
      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
        - geo_blocked
      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.