analytics.setAttribute()

vevee.analytics.setAttribute()POST /api/v1/attributes/valuessk_live_pk_live_ only when workspace flag is ON

Set a single attribute value on a person. The attribute must be declared in the dashboard first (see Attributes). The server enforces the definition’s type/options — invalid values are rejected.

Auth gating. From the browser (public key), setAttributeonly works when the workspace has “Client-side attribute writes” ON in Settings → Security. Default is OFF — write from your backend with a secret key instead.

Signature

vevee.analytics.setAttribute(args: {
  distinctId: string;            // your user id
  attribute: string;             // the key declared in the dashboard
  value: string | number | boolean | string[];   // type depends on the attribute definition
}): Promise<{
  personId: string;
  attribute: string;
  value: string | number | boolean | string[];
}>

Parameters

Name		Type	Description
`distinctId`	required	`string`	Your user’s identifier. 1–200 characters. Must match the id you use in `capture()`.
`attribute`	required	`string`	The attribute’s `key` as declared in the dashboard.
`value`	required	`string \| number \| boolean \| string[]`	Shape depends on the attribute’s declared type. The server coerces and validates against `config` (options, max_length, min/max, etc.). Arrays are only valid for `multi_choice` attributes.

Returns

The persisted result. value is what the server actually stored - it may be truncated or normalized from your input (e.g. multi_choice keeps only the subset that matches declared options).

Errors

Code	Status	When
`attribute_not_defined`	400	The key isn’t declared in the dashboard.
`attribute_value_invalid`	400	Value doesn’t match the type/config - e.g. not in `options` when `allow_custom: false`.
`attribute_value_too_long`	400	Exceeded the attribute’s `max_length`.
`attribute_archived`	400	The attribute exists but has been archived.
`client_attribute_writes_disabled`	403	Public-key write attempted but the workspace’s “Client-side attribute writes” flag is OFF.

Examples

Single choice written from the backend:

// 'persona' is declared in the dashboard as single_choice
// with options [teacher, student].
await vevee.analytics.setAttribute({
  distinctId: user.id,
  attribute: 'persona',
  value: 'teacher',
});

Multi-choice with an array:

// 'topics' is multi_choice with options [history, math, science, art].
await vevee.analytics.setAttribute({
  distinctId: user.id,
  attribute: 'topics',
  value: ['history', 'math'],  // server keeps only the matching subset
});

Related: setAttributes() for bulk writes, getAttributes() to read current values, clearAttribute() to remove a value, and the Attributes guide for declaring attribute schemas in the dashboard.