> ## 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.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.omni.co/feedback
```json
{
"path": "/api/user-model-roles/retrieve-user-model-roles",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Retrieve user model roles
> Retrieves the model role assignments for a user. This includes both direct role assignments and roles inherited from user group memberships.
## OpenAPI
````yaml /api/openapi.yaml get /v1/users/{userId}/model-roles
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: AI
description: AI-powered query generation
- 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: 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: Documents
description: Create, retrieve, and manage documents
- 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: Labels
description: >
Manage labels in an organization. Labels can be applied to documents and
folders to help organize and categorize content.
**Label types:**
- **Basic labels**: Can be created and managed by any user
- **Verified labels**: Indicate curated or officially sanctioned content.
Admin-only.
- **Homepage labels**: Appear on the organization homepage. Admin-only.
- name: Folders
description: Create and organize content 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: 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/users/{userId}/model-roles:
get:
tags:
- User model roles
summary: Retrieve user model roles
description: >
Retrieves the model role assignments for a user. This includes both
direct role assignments and roles inherited from user group memberships.
operationId: getUserModelRoles
parameters:
- name: userId
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the user to retrieve model roles for.
example: 9e8719d9-276a-4964-9395-a493189a247c
- name: modelId
in: query
schema:
type: string
format: uuid
description: >-
Filter results to a specific model ID. If not provided, returns
roles for all models the user has access to.
example: 7d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a
- name: connectionId
in: query
schema:
type: string
format: uuid
description: >-
Filter results to models from a specific connection. If not
provided, returns roles for all connections.
example: bc1f9c9f-208d-48a2-9ae3-ff80f2c79fed
responses:
'200':
description: User model roles retrieved successfully.
content:
application/json:
schema:
type: object
properties:
membershipId:
type: string
format: uuid
description: The ID of the user's membership in the organization.
results:
type: array
description: >-
Array of all role assignments for the user, including
direct assignments, roles inherited from user groups, and
connection base roles.
items:
type: object
properties:
modelId:
type: string
format: uuid
description: The ID of the model.
connectionId:
type: string
format: uuid
description: The ID of the connection.
roleName:
type: string
description: The role name for this assignment.
baseRole:
type: string
description: The base role for this assignment.
priority:
type: integer
description: >-
The priority of this role assignment. Higher values
take precedence.
resolved:
type: boolean
description: >-
If `true`, this is the highest priority role for the
model. This is the role that will be used when
determining the user's effective permissions.
from:
type: object
description: >-
Information about where this role assignment comes
from.
properties:
type:
type: string
description: >
The type of role assignment:
- `User Role` - Direct role assignment to the
user
- `Group Role` - Role inherited from a user
group
- `Connection Base Role` - Default role from the
connection
miniUuid:
type: string
description: >-
The short ID of the user group. Only present for
`Group Role` type.
name:
type: string
description: >-
The name of the user group. Only present for
`Group Role` type.
depth:
type: integer
description: >-
The depth of group nesting. Only present for
`Group Role` type.
example:
membershipId: 9633bd79-7bdf-4773-8952-8fdd4098e51c
results:
- baseRole: MODELER
from:
type: User Role
priority: 350
resolved: true
roleName: MODELER
connectionId: 8a464dc9-1f0e-4a9e-86fa-e1e6d970157c
modelId: 5fb90312-67b1-4cca-823a-9a341d549320
- baseRole: QUERIER
from:
depth: 0
miniUuid: PgjffoEu
name: Super Group
type: Group Role
priority: 250
resolved: false
roleName: QUERIER
connectionId: 8a464dc9-1f0e-4a9e-86fa-e1e6d970157c
modelId: 5fb90312-67b1-4cca-823a-9a341d549320
- baseRole: VIEWER
from:
type: Connection Base Role
priority: 50
resolved: false
roleName: VIEWER
connectionId: 8a464dc9-1f0e-4a9e-86fa-e1e6d970157c
modelId: 5fb90312-67b1-4cca-823a-9a341d549320
'404':
description: User not found in organization.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: User not found in organization
status: 404
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- bearerAuth: []
components:
schemas:
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
responses:
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#personal-access-tokens-pat).
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`
````