Skip to main content

​
Endpoint

PUT /recipe/user/metadata
This is an app-specific API that updates or creates metadata for a user. The metadata update is performed as a shallow merge.

​
Request Body

​
userId
string
required
The ID of the user whose metadata you want to update.
​
metadataUpdate
object
required
A JSON object containing the metadata fields to update or add. This will be shallow-merged with existing metadata.

​
Request Example

curl -X PUT https://your-api-domain.com/recipe/user/metadata \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "metadataUpdate": {
      "preferences": {
        "theme": "dark",
        "language": "en"
      },
      "accountType": "premium"
    }
  }'

​
Response

​
status
string
Always returns "OK"
​
metadata
object
The complete metadata object after the update has been applied.

​
Response Example

{
  "status": "OK",
  "metadata": {
    "preferences": {
      "theme": "dark",
      "language": "en"
    },
    "accountType": "premium",
    "lastLoginLocation": "New York"
  }
}

​
Implementation Details

Source: View source
  • This API requires public tenant access
  • Metadata updates are performed as a shallow merge
    • New fields are added
    • Existing fields are updated
    • Fields not in metadataUpdate remain unchanged
  • User ID mapping is automatically handled for app-specific queries
  • Returns the complete, updated metadata object

​
Merge Behavior Example

If existing metadata is: 
{
  "theme": "light",
  "notifications": true,
  "lastLogin": "2024-01-01"
}
And you send an update: 
{
  "metadataUpdate": {
    "theme": "dark",
    "language": "en"
  }
}
The resulting metadata will be: 
{
  "theme": "dark",
  "notifications": true,
  "lastLogin": "2024-01-01",
  "language": "en"
}

​
Use Cases

  • Store user preferences and settings
  • Save custom profile information
  • Track user-specific application state
  • Maintain feature flags per user

Get User Metadata

Retrieve existing metadata for a user

Build docs developers (and LLMs) love

Get started for freeTalk to us