Creating Profiles

This guide explains how to create and update user profiles.

Overview

Profiles are automatically created when first accessed, but you can also create or update them explicitly. Profiles include a display name and avatar URL.

Get or Create Profile

The simplest way to create a profile is to request it. If it doesn't exist, it will be created automatically.

Endpoint:

GET /v1/profiles/user/{user_id}

Example Request:

GET /v1/profiles/user/user_123

Response:

{
  "tenant_id": "your_tenant",
  "user_id": "user_123",
  "name": "Brave Tiger 42",
  "avatar_url": "https://api.dicebear.com/9.x/adventurer/svg?seed=your_tenant_user_123",
  "created_at": "2026-01-28T10:00:00Z",
  "updated_at": "2026-01-28T10:00:00Z"
}

If the profile doesn't exist, the system will:

Generate a random name (e.g., "Brave Tiger 42")
Create an avatar URL based on the tenant ID and user ID
Create the profile and return it

Update Profile

Update an existing profile or create one with a custom name.

Endpoint:

PUT /v1/profiles/user/{user_id}

Request Body:

{
  "name": "John Doe",
  "regenerate_avatar": false
}

Fields:

name - Optional. New display name. If not provided, keeps existing name or generates one.
regenerate_avatar - Optional. If true, generates a new avatar URL.

Example Request:

PUT /v1/profiles/user/user_123
Content-Type: application/json

{
  "name": "John Doe"
}

Response:

{
  "tenant_id": "your_tenant",
  "user_id": "user_123",
  "name": "John Doe",
  "avatar_url": "https://api.dicebear.com/9.x/adventurer/svg?seed=your_tenant_user_123",
  "created_at": "2026-01-28T10:00:00Z",
  "updated_at": "2026-01-28T10:05:00Z"
}

Regenerate Avatar

To generate a new avatar for a user:

Request:

{
  "regenerate_avatar": true
}

This will create a new avatar URL based on the current timestamp, giving the user a fresh avatar while maintaining consistency (same seed = same avatar).

Create Profile with Custom Name

To create a profile with a specific name from the start:

Request:

{
  "name": "Custom User Name"
}

If the profile doesn't exist, it will be created with your provided name. If it exists, the name will be updated.

Profile Properties

Property	Type	Description
`tenant_id`	string	Tenant identifier
`user_id`	string	User identifier
`name`	string	Display name
`avatar_url`	string	Avatar image URL
`created_at`	datetime	When profile was created
`updated_at`	datetime	Last update time

JavaScript Example

class ProfileClient {
  constructor(apiUrl, jwt) {
    this.apiUrl = apiUrl;
    this.jwt = jwt;
  }

  async getProfile(tenantId, userId) {
    const response = await fetch(
      `${this.apiUrl}/v1/profiles/user/${userId}`,
      {
        headers: {
          'Authorization': `Bearer ${this.jwt}`,
          'Content-Type': 'application/json'
        }
      }
    );
    return response.json();
  }

  async updateProfile(tenantId, userId, name, regenerateAvatar = false) {
    const response = await fetch(
      `${this.apiUrl}/v1/profiles/user/${userId}`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${this.jwt}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          name,
          regenerate_avatar: regenerateAvatar
        })
      }
    );
    return response.json();
  }
}

// Example usage
const profile = new ProfileClient('https://query.phoenix.example.com', userJwt);

// Get or create profile (auto-creates if doesn't exist)
const userProfile = await profile.getProfile('tenant_abc', 'user_123');
console.log(`User: ${userProfile.name}`);
console.log(`Avatar: ${userProfile.avatar_url}`);

// Update profile name
const updated = await profile.updateProfile('tenant_abc', 'user_123', 'John Doe');
console.log(`Updated name: ${updated.name}`);

// Regenerate avatar
const newAvatar = await profile.updateProfile('tenant_abc', 'user_123', null, true);
console.log(`New avatar: ${newAvatar.avatar_url}`);

Best Practices

Lazy Creation: Don't pre-create profiles. Let them be created automatically when first accessed.
Name Validation: Validate names on your side before updating (length, characters, etc.).
Avatar Consistency: Avatars are consistent per user (same seed = same avatar), so you can cache them.
Update Frequency: Don't update profiles too frequently. Cache profile data in your application.
Error Handling: Handle cases where profile updates fail gracefully.

Next Steps

Querying Profiles - Learn how to retrieve profile information
Profile Overview - Understand the profile system

Creating Profiles

On this page