class

Anthropic::BetaUserProfiles

User Profiles API (beta) for creating and managing per-end-user state.

Access via client.beta.user_profiles.

profile = client.beta.user_profiles.create(
  external_id: "user-123",
  metadata: {"plan" => "pro"}
)

enrollment = client.beta.user_profiles.create_enrollment_url(profile.id)
puts enrollment.url

# Pass the profile id when creating a message so the API applies
# per-user state like memory.
client.beta.messages.create(
  model: Anthropic::Model::CLAUDE_OPUS_4_7,
  max_tokens: 1024,
  messages: [Anthropic::MessageParam.user("Hi!")],
  user_profile_id: profile.id
)

Constants

BETA_HEADER = USER_PROFILES_BETA

Constructors

new(client : Client)

Source

Instance methods

Create a new user profile.

external_user_details is accepted under the user-profiles-2026-09-04 beta only (attached automatically when the details are present); under that revision send external_user_details.reference_id instead of external_id.

Source

create_enrollment_url(user_profile_id : String, betas : Array(String) = [] of String, workspace_id : String | Nil = nil) : BetaUserProfileEnrollmentURL

Create an enrollment URL for the given user profile.

Send the returned URL to the end user so they can complete enrollment.

Source

list(limit : Int32 = 20, order : String | Nil = nil, order_by : String | Nil = nil, page : String | Nil = nil, betas : Array(String) = [] of String, workspace_id : String | Nil = nil) : BetaUserProfileListResponse

List user profiles with optional pagination.

order may be "asc" or "desc". order_by selects the sort key (e.g. "name").

Source

retrieve(user_profile_id : String, betas : Array(String) = [] of String, workspace_id : String | Nil = nil) : BetaUserProfile

Retrieve a user profile by ID.

Source

update(user_profile_id : String, external_id : String | Nil = nil, metadata : Hash(String, String) | Nil = nil, access_type : String | Nil = nil, name : String | Nil = nil, external_user_onboarded_at : String | Nil = nil, external_user_details : BetaUserProfileExternalUserDetails | Hash(String, JSON::Any) | Nil = nil, betas : Array(String) = [] of String, workspace_id : String | Nil = nil) : BetaUserProfile

Update metadata or external_id for an existing user profile.

To remove a metadata key, set its value to an empty string. Keys not provided are left unchanged.

Source