Update User Metadata

curl --request POST \
  --url https://asteragents.com/api/admin/updateUserMetadata \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "<string>",
  "metadata": {}
}
'

import requests

url = "https://asteragents.com/api/admin/updateUserMetadata"

payload = {
    "userId": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({userId: '<string>', metadata: {}})
};

fetch('https://asteragents.com/api/admin/updateUserMetadata', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://asteragents.com/api/admin/updateUserMetadata",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://asteragents.com/api/admin/updateUserMetadata"

	payload := strings.NewReader("{\n  \"userId\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://asteragents.com/api/admin/updateUserMetadata")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://asteragents.com/api/admin/updateUserMetadata")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userId\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "400": {},
  "401": {},
  "403": {},
  "405": {},
  "500": {},
  "success": true,
  "user": {
    "id": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "publicMetadata": {}
  }
}

POST

admin

updateUserMetadata

Update User Metadata

curl --request POST \
  --url https://asteragents.com/api/admin/updateUserMetadata \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "<string>",
  "metadata": {}
}
'

import requests

url = "https://asteragents.com/api/admin/updateUserMetadata"

payload = {
    "userId": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({userId: '<string>', metadata: {}})
};

fetch('https://asteragents.com/api/admin/updateUserMetadata', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://asteragents.com/api/admin/updateUserMetadata",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://asteragents.com/api/admin/updateUserMetadata"

	payload := strings.NewReader("{\n  \"userId\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://asteragents.com/api/admin/updateUserMetadata")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"userId\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://asteragents.com/api/admin/updateUserMetadata")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"userId\": \"<string>\",\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "400": {},
  "401": {},
  "403": {},
  "405": {},
  "500": {},
  "success": true,
  "user": {
    "id": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "publicMetadata": {}
  }
}

This endpoint requires organization admin privileges. Only users with the org:admin role can update user metadata.

Organization-Scoped Metadata: Metadata set through this endpoint is specific to the user’s membership in your organization. If the same user belongs to multiple organizations, each organization maintains separate metadata.

Update custom metadata for a user within your organization. Perfect for managing user roles, departments, teams, or any custom properties needed for filtering and organization.

Authentication

string

required

Bearer token for authentication. Must be from a user with org:admin role.

Body

string

required

Clerk user ID of the user whose metadata should be updated

object

required

Key-value pairs of metadata to set for the user. This completely replaces existing metadata.

Show Common Metadata Fields

role: User’s role or job title (e.g., “manager”, “developer”)
department: Department name (e.g., “engineering”, “marketing”)
team: Team assignment (e.g., “backend”, “frontend”)
level: Seniority level (e.g., “senior”, “junior”)
vnum: Vendor or employee number
Custom fields: Any key-value pairs relevant to your organization

Response

boolean

Whether the metadata update was successful

object

Updated user information

Show User Object

string

Clerk user ID

string

User’s email address

string

User’s first name

string

User’s last name

object

The updated organization-scoped metadata

Examples

curl -X POST https://asteragents.com/api/admin/updateUserMetadata \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_2ABC123DEF",
    "metadata": {
      "role": "senior-developer",
      "department": "engineering",
      "team": "backend"
    }
  }'

import requests

url = "https://asteragents.com/api/admin/updateUserMetadata"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "userId": "user_2ABC123DEF",
    "metadata": {
        "role": "manager",
        "department": "engineering",
        "level": "senior",
        "vnum": "EMP-12345"
    }
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(f"Updated metadata for {result['user']['email']}")

const response = await fetch('https://asteragents.com/api/admin/updateUserMetadata', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: 'user_2ABC123DEF',
    metadata: {
      role: 'developer',
      department: 'engineering',
      team: 'frontend'
    }
  })
});

const result = await response.json();
console.log('Updated user:', result.user.email);

{
  "success": true,
  "user": {
    "id": "user_2ABC123DEF",
    "email": "john.doe@company.com",
    "firstName": "John",
    "lastName": "Doe",
    "publicMetadata": {
      "role": "senior-developer",
      "department": "engineering",
      "team": "backend"
    }
  }
}

Error Codes

object

Bad Request - Invalid request data or validation errors

object

Unauthorized - Invalid or missing authentication

object

Forbidden - User is not an admin in the organization, or target user is not a member of the organization

object

Method Not Allowed - Only POST requests are accepted

object

Internal Server Error - Unexpected error occurred

Use Cases

Department Management

Assign users to departments for organizational filtering:

await fetch('/api/admin/updateUserMetadata', {
  method: 'POST',
  headers: headers,
  body: JSON.stringify({
    userId: 'user_123',
    metadata: {
      department: 'marketing',
      role: 'content-writer',
      team: 'social-media'
    }
  })
});

Role-Based Access Control

Set roles that can be used for filtering in the dashboard:

# Promote user to manager
requests.post('/api/admin/updateUserMetadata',
    headers=headers,
    json={
        'userId': 'user_456',
        'metadata': {
            'role': 'manager',
            'department': 'engineering',
            'level': 'senior',
            'manages_team': 'backend'
        }
    })

Custom Properties

Store any custom data relevant to your organization:

// Track contractor information
await fetch('/api/admin/updateUserMetadata', {
  method: 'POST',
  headers: headers,
  body: JSON.stringify({
    userId: 'user_789',
    metadata: {
      employment_type: 'contractor',
      contract_end_date: '2024-12-31',
      hourly_rate: 'tier-3',
      vnum: 'CON-9876'
    }
  })
});

Workflow

Step 1: Get User ID

First, retrieve the user ID from the Get Organization Users endpoint:

const usersResponse = await fetch('/api/admin/getUsersInOrg', {
  headers: { 'Authorization': 'Bearer ' + token }
});
const users = await usersResponse.json();

// Find the user you want to update
const targetUser = users.find(u => u.email === 'john@company.com');

Step 2: Update Metadata

Then update their metadata:

await fetch('/api/admin/updateUserMetadata', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: targetUser.id,
    metadata: {
      role: 'senior-developer',
      department: 'engineering'
    }
  })
});

Features

Organization Isolation: Complete metadata separation between organizations.

Per-Organization Metadata: Same user in different orgs has independent metadata
Complete Replacement: Metadata object completely replaces existing metadata (not merged)
Real-time Updates: Changes are immediately reflected in dashboard filters and user listings
Flexible Schema: Store any JSON-serializable data structure
Dashboard Integration: Use metadata for filtering conversations and statistics

Important Notes

Metadata Replacement: This endpoint completely replaces the user’s metadata in your organization. To preserve existing fields, fetch current metadata first and merge your changes before updating.

Metadata is scoped to the organization - each org maintains separate metadata for shared users
Removing a user from the organization deletes their metadata for that org
Re-adding a user creates fresh metadata (previous metadata is not restored)
Metadata can contain any JSON-serializable data (strings, numbers, booleans, objects, arrays)
Changes are reflected immediately in dashboard filters

Security Notes

Only organization admins can update user metadata
Target user must be a member of your organization
Cannot update metadata for users in other organizations
Metadata is visible in API responses to all org members

Use this endpoint with Get Organization Users to build powerful user management workflows and custom dashboards.

API Documentation

Admin API

Files API

Agents API

Tools API

Agent Tags API

Knowledge Bases API

Skills API

Conversations API

Scheduled Tasks API

Other Endpoints

Legacy Endpoints (Deprecated)

Update User Metadata

Authentication

Body

Response

Examples

Error Codes

Use Cases

Department Management

Role-Based Access Control

Custom Properties

Workflow

Step 1: Get User ID

Step 2: Update Metadata

Features

Important Notes

Security Notes

​Authentication

​Body

​Response

​Examples

​Error Codes

​Use Cases

​Department Management

​Role-Based Access Control

​Custom Properties

​Workflow

​Step 1: Get User ID

​Step 2: Update Metadata

​Features

​Important Notes

​Security Notes

Authentication

Body

Response

Examples

Error Codes

Use Cases

Department Management

Role-Based Access Control

Custom Properties

Workflow

Step 1: Get User ID

Step 2: Update Metadata

Features

Important Notes

Security Notes