Update Profile

Update an existing profile. 409 when two attached secrets share a key.

PATCH /agents/v2/profiles/{profileId}

Update Profile

cURL

curl --request PATCH \
  --url https://odyssey.asteroid.ai/agents/v2/profiles/{profileId} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "cookiesToAdd": [
    {
      "domain": "<string>",
      "httpOnly": true,
      "key": "<string>",
      "name": "<string>",
      "secure": true,
      "value": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "expiry": "2023-11-07T05:31:56Z",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "cookiesToDelete": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "credentialsToAdd": [
    {
      "data": "<string>",
      "name": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "credentialsToDelete": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "credentialsToUpdate": [
    {
      "data": "<string>",
      "name": "<string>"
    }
  ],
  "description": "<string>",
  "fingerprintId": "<string>",
  "inboxEmailPrefix": "<string>",
  "name": "<string>",
  "secretIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "secretIdsToAdd": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "secretIdsToRemove": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "stickyIP": true,
  "tracingEnabled": true,
  "vaultItemIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "vaultItemIdsToAdd": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "vaultItemIdsToRemove": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

200

{
  "cookies": [
    {
      "domain": "<string>",
      "httpOnly": true,
      "key": "<string>",
      "name": "<string>",
      "sameSite": "Strict",
      "secure": true,
      "value": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "expiry": "2023-11-07T05:31:56Z",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "credentials": [
    {
      "data": "<string>",
      "name": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "description": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "inboxEmail": "<string>",
  "name": "<string>",
  "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "stickyIP": true,
  "tracingEnabled": true,
  "updatedAt": "2023-11-07T05:31:56Z",
  "vaultItems": [
    {
      "fields": [
        {
          "key": "<string>",
          "placeholder": "<string>",
          "type": "username",
          "legacyPlaceholder": "<string>"
        }
      ],
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "itemKey": "<string>",
      "kind": "login",
      "name": "<string>"
    }
  ],
  "fingerprintId": "<string>",
  "inboxEmailPrefix": "<string>"
}

Authorizations

X-Api-Key · string · header · required

Path Parameters

profileId · string<uuid> · required

Body

application/json

Request to update an existing agent profile

cookiesToAdd · object[] · deprecated

Show child attributes

cookiesToDelete · string<uuid>[] · deprecated

credentialsToAdd · object[] · deprecated

Deprecated: use secretIds. Credentials to add to the profile.

Show child attributes

credentialsToDelete · string<uuid>[] · deprecated

Deprecated: use secretIds. IDs of credentials to remove from the profile.

credentialsToUpdate · object[] · deprecated

Deprecated: use secretIds. Credentials to update by name (matched case-insensitively).

Show child attributes

description · string

Maximum string length: 1000

fingerprintId · string

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. An empty string clears it; omit to leave unchanged. Null is rejected — the generated servers cannot tell null from an omitted field, so accepting it would turn an intended clear into a silent no-op.

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.

name · string

Required string length: 1 - 255

secretIds · string<uuid>[]

Secret IDs attached to this profile. Replaces the full list. To change part of it, use secretIdsToAdd and secretIdsToRemove.

secretIdsToAdd · string<uuid>[]

Secret IDs to attach. Secrets already attached stay. Cannot be combined with secretIds.

secretIdsToRemove · string<uuid>[]

Secret IDs to detach. IDs that are not attached are ignored. Applied before secretIdsToAdd. Cannot be combined with secretIds.

stickyIP · boolean

Turn the dedicated IP on or off. A change clears the profile's saved browser state, and is refused while a run uses the profile.

tracingEnabled · boolean

Whether browser tracing is enabled (admin only)

vaultItemIds · string<uuid>[] · deprecated

Deprecated: use secretIds.

vaultItemIdsToAdd · string<uuid>[] · deprecated

Deprecated: use secretIdsToAdd.

vaultItemIdsToRemove · string<uuid>[] · deprecated

Deprecated: use secretIdsToRemove.

Response

200

application/json

The request has succeeded.

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

Show child attributes

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.

Show child attributes

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.

Show child attributes

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.