> ## 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.

# Update Agent Profile

> Update an existing agent profile



## OpenAPI

````yaml https://odyssey.asteroid.ai/agents/v2/openapi.yaml patch /agent-profiles/{profileId}
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: Execution
  - name: Files
  - name: Agent Profiles
  - name: Agent Profile Pools
  - name: Workflows
  - name: Schema
  - name: Documentation
  - name: Context
paths:
  /agent-profiles/{profileId}:
    patch:
      tags:
        - Agent Profiles
      summary: Update Agent Profile
      description: Update an existing agent profile
      operationId: AgentProfileUpdate
      parameters:
        - description: The ID of the agent profile
          in: path
          name: profileId
          required: true
          schema:
            $ref: '#/components/schemas/Common.uuid'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Agents.Profile.UpdateAgentProfileRequest'
        description: Fields to update
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agents.Profile.AgentProfile'
          description: The request has succeeded.
        '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.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.InternalServerErrorBody'
          description: Server error
components:
  schemas:
    Common.uuid:
      format: uuid
      type: string
    Agents.Profile.UpdateAgentProfileRequest:
      description: Request to update an existing agent profile
      properties:
        adblockActive:
          description: Whether to enable ad blocking
          type: boolean
        cachePersistence:
          description: Whether to persist browser cache between sessions
          type: boolean
        captchaSolverActive:
          description: Whether the captcha solver should be active (managed proxy only)
          type: boolean
        cookiesToAdd:
          description: Cookies to add to the profile
          items:
            $ref: '#/components/schemas/Agents.Profile.Cookie'
          type: array
        cookiesToDelete:
          description: IDs of cookies to remove from the profile
          items:
            $ref: '#/components/schemas/Common.uuid'
          type: array
        credentialsToAdd:
          description: Credentials to add to the profile
          items:
            $ref: '#/components/schemas/Agents.Profile.Credential'
          type: array
        credentialsToDelete:
          description: IDs of credentials to remove from the profile
          items:
            $ref: '#/components/schemas/Common.uuid'
          type: array
        credentialsToUpdate:
          description: Credentials to update by name (matched case-insensitively)
          items:
            $ref: '#/components/schemas/Agents.Profile.CredentialUpdate'
          type: array
        customProxy:
          allOf:
            - $ref: '#/components/schemas/Agents.Profile.CustomProxyConfigInput'
          description: Custom proxy configuration (for custom proxy mode)
        description:
          description: New description for the profile
          maxLength: 1000
          type: string
        extraStealth:
          description: Whether to enable extra stealth mode
          type: boolean
        forcePopupsAsTabsActive:
          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:
          description: Whether to enable media blocking (images, videos, etc.)
          type: boolean
        name:
          description: New name for the profile
          maxLength: 255
          minLength: 1
          type: string
        operatingSystem:
          allOf:
            - $ref: '#/components/schemas/Agents.Profile.OperatingSystem'
          description: Operating system to emulate
        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)
        tracingEnabled:
          description: Whether browser tracing is enabled (admin only)
          type: boolean
      type: object
    Agents.Profile.AgentProfile:
      description: An agent profile containing browser configuration and credentials
      properties:
        adblockActive:
          description: Whether to enable ad blocking
          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:
          description: List of credentials associated with this profile
          items:
            $ref: '#/components/schemas/Agents.Profile.Credential'
          type: array
        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
        extraStealth:
          description: Whether extra stealth mode is enabled
          type: boolean
        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
      required:
        - id
        - name
        - description
        - organizationId
        - proxyMode
        - captchaSolverActive
        - stickyIP
        - extraStealth
        - cachePersistence
        - adblockActive
        - popupBlockerActive
        - forcePopupsAsTabsActive
        - mediaBlockerActive
        - pdfViewerActive
        - tracingEnabled
        - 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.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.CredentialUpdate:
      description: Request to update an existing credential by name
      properties:
        data:
          description: New credential value (plaintext - will be encrypted server-side)
          minLength: 1
          type: string
        name:
          description: >-
            Name of the credential to update (case-insensitive, will be matched
            as uppercase)
          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
    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
        - residential
        - mobile
      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.SameSite:
      description: SameSite attribute for cookies
      enum:
        - Strict
        - Lax
        - None
      type: string
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-Asteroid-Agents-Api-Key
      type: apiKey

````