> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Update a user attribute definition
>
**Organization Admin** permissions are required to use this endpoint.
Update a custom [user attribute](/administration/users/attributes) definition. Omitted fields keep their current values. The attribute's `type` cannot change, and a multiple-values attribute cannot be changed back to a single value.
## OpenAPI
````yaml /api/openapi.yaml put /v1/user-attributes/{userAttributeId}
openapi: 3.1.0
info:
title: Omni API
description: >
The Omni REST API provides programmatic access to your Omni instance for
managing users, documents, queries, schedules, and more.
version: 1.0.0
contact:
name: Omni Support
url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
description: Production
variables:
instance:
default: blobsrus
description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
description: Playground
variables:
instance:
default: blobsrus
description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: Who Am I
description: Inspect your own user permissions
- name: AI
description: AI-powered query generation
- name: AI Credit Controls
description: Manage organization-level AI credit usage
- name: AI Credit Usage
description: Monitor AI credit usage
- name: AI Evals
description: >-
Manage prompt sets and runs used to score AI quality against curated
prompt suites.
- name: AI Model Suggestions
description: Manage AI-generated suggestions for shared models
- name: AI Routines
description: >-
Manage Routines, which are scheduled, recurring AI-powered tasks that run
automatically on your data
- name: Apps
description: Draft and publish app documents.
- name: Documents v2
description: >
A draft-based workflow for creating and editing documents: create a
document, patch a draft, then publish.
- name: Documents
description: Create, retrieve, and manage documents
- name: API Tokens
description: >-
Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
grants)
- name: Connections
description: Manage database connections
- name: Connection environments
description: Manage connection environments database connections
- name: Color Palettes
description: Manage custom chart color palettes
- name: Content
description: Unified content retrieval (documents and folders)
- name: Content migration
description: Export and import dashboards
- name: Content validator
description: Validate content against models and perform find/replace operations
- name: Dashboard downloads
description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
- name: Dashboard filters and controls
description: Read and update dashboard filter and control default values
- name: dbt
description: Manage dbt configuration for connections
- name: Document favorites
description: Favorite and unfavorite documents
- name: Document labels
description: Apply and manage labels on documents
- name: Document permissions
description: Manage document-level access
- name: Embed
description: Manage embed sessions
- name: Labels
description: |
Manage labels in the organization
- name: Folders
description: Create and organize content folders
- name: Folder labels
description: Apply and manage labels on folders
- name: Folder permissions
description: Manage folder-level access
- name: Jobs
description: Check status of asynchronous jobs
- name: Models
description: Create and manage data models
- name: Model branches
description: Manage model branches and merge changes
- name: Model git configuration
description: Manage git configuration for shared models
- name: Queries
description: Execute workbook queries
- name: Schedules
description: Create and manage scheduled tasks
- name: Schedule recipients
description: Manage schedule recipients
- name: Schema refresh schedules
description: Manage automated schema refresh schedules for connections
- name: Skills
description: >-
Manage skills, the saved slash-command instructions the Omni AI assistant
runs
- name: Topics
description: Retrieve topic information from models
- name: Uploads
description: Manage file uploads
- name: Users
description: Manage users
- name: User attributes
description: Manage user attribute definitions
- name: User groups
description: Manage user groups
- name: User model roles
description: Manage model and connection role assignments for users
- name: User group model roles
description: Manage model and connection role assignments for user groups
- name: Uploads
description: Manage CSV and spreadsheet uploads
paths:
/v1/user-attributes/{userAttributeId}:
put:
tags:
- User attributes
summary: Update a user attribute definition
description: >
**Organization Admin** permissions are required to use this endpoint.
Update a custom [user attribute](/administration/users/attributes)
definition. Omitted fields keep their current values. The attribute's
`type` cannot change, and a multiple-values attribute cannot be changed
back to a single value.
operationId: userAttributesUpdate
parameters:
- $ref: '#/components/parameters/userAttributeId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserAttributeObject'
example:
label: Region
name: region
default_value: us-east
description: User region for row-level security filtering
multiple_values: false
responses:
'200':
description: User attribute definition updated
content:
application/json:
schema:
type: object
required:
- default_value
- description
- id
- label
- multiple_values
- name
- system
- type
properties:
default_value:
$ref: '#/components/schemas/UserAttributeDefaultValue'
description: >
Default value applied when no user-specific value is set.
When `multiple_values` is `true`, this is an array. Null
if no default is configured.
description:
$ref: '#/components/schemas/UserAttributeDescription'
id:
$ref: '#/components/schemas/UserAttributeId'
label:
$ref: '#/components/schemas/UserAttributeLabel'
description: Display name shown in the Omni UI
multiple_values:
$ref: '#/components/schemas/UserAttributeMultipleValues'
description: >
Whether the attribute accepts an array of values. When
`true`, `default_value` and user-specific values are
arrays.
name:
$ref: '#/components/schemas/UserAttributeName'
description: >
Reference name used in model SQL and in embed SSO URL
parameters
system:
$ref: '#/components/schemas/UserAttributeSystem'
type:
$ref: '#/components/schemas/UserAttributeType'
description: >
Data type that determines valid values. `String`
attributes accept text, `Number` attributes accept numeric
values stored as strings for precision.
example:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: region
label: Region
type: String
multiple_values: false
default_value: us-east
description: User region for row-level security filtering
system: false
'400':
description: >
Bad Request. The request body or the `userAttributeId` parameter
failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
example:
detail: 'Bad Request: id: Invalid UUID'
status: 400
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError401'
example:
detail: 'Unauthorized: Missing or invalid API key'
status: 401
'403':
description: |
Forbidden. Requires Organization Admin permissions.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError403'
example:
detail: You do not have permission to manage user attributes
status: 403
'404':
description: >
Not Found. No user attribute definition with that ID exists in the
caller's organization.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
example:
detail: User attribute definition does not exist
status: 404
'405':
$ref: '#/components/responses/MethodNotAllowed'
'409':
description: >
Conflict. Another user attribute definition already has this name or
label, or the definition changed while it was being updated.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError409'
example:
detail: A user attribute named "region" already exists
status: 409
'429':
$ref: '#/components/responses/TooManyRequests'
components:
parameters:
userAttributeId:
name: userAttributeId
in: path
required: true
description: User attribute ID
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
schemas:
UserAttributeObject:
type: object
properties:
default_value:
$ref: '#/components/schemas/UserAttributeDefaultValue'
description:
$ref: '#/components/schemas/UserAttributeDescription'
id:
$ref: '#/components/schemas/UserAttributeId'
label:
$ref: '#/components/schemas/UserAttributeLabel'
multiple_values:
$ref: '#/components/schemas/UserAttributeMultipleValues'
name:
$ref: '#/components/schemas/UserAttributeName'
system:
$ref: '#/components/schemas/UserAttributeSystem'
type:
$ref: '#/components/schemas/UserAttributeType'
UserAttributeDefaultValue:
description: >
Default value applied when no user-specific value is set. A single value
when `multiple_values` is `false`, an array when it is `true`.
Strings are trimmed. Number attributes accept numbers or numeric strings
and store them as strings. Numbers are converted to strings on receipt;
send anything beyond the JSON safe integer range (`2^53 - 1`) as a
string or it loses precision before Omni sees it. Null or a string that
trims to empty means no default.
An empty array clears the default of a multi-valued attribute and is
rejected for a single-valued attribute. A list member that trims to
empty is rejected.
anyOf:
- type: string
- type: number
minimum: -1.7976931348623157e+308
maximum: 1.7976931348623157e+308
- type: array
items:
anyOf:
- type: string
- type: number
minimum: -1.7976931348623157e+308
maximum: 1.7976931348623157e+308
- type: 'null'
example: us-east
UserAttributeDescription:
type: string
nullable: true
description: >
Human-readable description of the attribute and its purpose. An empty
string is stored as null.
example: User region for row-level security filtering
UserAttributeId:
name: id
type: string
description: >-
Unique identifier for custom attributes. Empty string for system-defined
attributes.
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
UserAttributeLabel:
name: label
type: string
minLength: 1
description: >
Display name shown in the Omni UI. Unique among the custom attributes in
the organization, and may match the label of a system attribute.
Must not start with `Omni` and must not be one of the reserved
connection labels: `Host`, `Password`, `Database`, `Port`, `Schema`,
`Connection Name`.
example: Region
UserAttributeMultipleValues:
name: multiple_values
type: boolean
default: false
description: Whether the attribute accepts an array of values.
example: false
UserAttributeName:
name: name
type: string
minLength: 1
description: >-
Reference name used in model SQL and in embed SSO URL parameters. Unique
within the organization. Must start with a letter, contain only letters,
numbers and underscores, and must not start with `omni_`.
example: region
UserAttributeSystem:
name: system
type: boolean
description: >
System-defined attributes (e.g. `omni_user_id`, `omni_user_email`) are
built-in and read-only. Custom attributes have a `false` value.
example: false
UserAttributeType:
name: type
type: string
enum:
- String
- Number
description: >
Data type that determines valid values. `String` attributes accept text,
`Number` attributes accept numeric values stored as strings for
precision. Immutable after creation.
example: String
ApiError400:
type: object
properties:
detail:
type: string
description: Human-readable error message describing what went wrong.
status:
type: integer
description: HTTP status code of the error.
example: 400
required:
- detail
- status
ApiError401:
type: object
properties:
detail:
type: string
description: Human-readable error message describing what went wrong.
example: 'Unauthorized: Missing or invalid API key'
status:
type: integer
description: HTTP status code of the error.
example: 401
required:
- detail
- status
ApiError403:
type: object
properties:
detail:
type: string
description: Human-readable error message describing what went wrong.
status:
type: integer
description: HTTP status code of the error.
example: 403
required:
- detail
- status
ApiError404:
type: object
properties:
detail:
type: string
description: Human-readable error message describing what went wrong.
status:
type: integer
description: HTTP status code of the error.
example: 404
required:
- detail
- status
ApiError409:
type: object
properties:
detail:
type: string
description: Human-readable error message describing what went wrong.
status:
type: integer
description: HTTP status code of the error.
example: 409
required:
- detail
- status
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
responses:
MethodNotAllowed:
description: Method Not Allowed - Invalid HTTP method for this endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Too Many Requests - Rate limit exceeded (60 requests/minute)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Can be either an [Organization API
Key](/api/authentication#organization-api-keys) or [Personal Access
Token (PAT)](/api/authentication#token-types).
Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
orgApiKey:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Requires an [Organization API
Key](/api/authentication#organization-api-keys). Personal Access Tokens
(PATs) are not supported for this endpoint.
Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`
````