Vertesia User Groups API

openapi: 3.2.0
info:
  title: Vertesia User Groups API
  version: 1.6.0-dev.20261019.172735Z
  x-api-version: '20260803'
  description: The Vertesia API provides project-scoped access to interaction execution and content workflows. Use it to run interactions, inspect execution history, stream run progress, replay previous executions, and search content objects and collections. Authenticate requests with a bearer token, or use the official `@vertesia/client` package for typed access from Node.js applications.
  contact:
    name: Vertesia
    url: https://vertesiahq.com/
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  x-scalar-sdk-installation:
  - lang: Node
    description: 'Install the **Vertesia Client** from npm:'
    source: npm install @vertesia/client
servers:
- url: https://api.{region}.vertesia.io/api/v1
  description: Vertesia API
  variables:
    region:
      default: us1
      enum:
      - us1
      - eu1
      - jp1
      description: Regional API host label. `us1` is the global endpoint.
tags:
- name: User Groups
  description: User Group endpoints manage account-level groups and their membership for access control and app visibility.
paths:
  /iam/groups:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: ListUserGroups
      tags:
      - User Groups
      summary: List user groups
      description: 'Lists user groups in the current account. Pass `project` to return only groups usable in that project (org-wide groups plus groups restricted to it).


        **Required permissions:** Any of `account:read`, `account:group:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:read
      parameters:
      - name: search
        in: query
        required: false
        schema:
          type: string
      - name: tags
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: limit
        in: query
        required: false
        schema:
          type: number
      - name: offset
        in: query
        required: false
        schema:
          type: number
      - name: project
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: User groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroupArray'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:read
      - account:group:read
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/groups.ts
        className: UserGroupsResource
        methodName: list
    post:
      operationId: CreateUserGroup
      tags:
      - User Groups
      summary: Create a user group
      description: 'Creates a new user group in the current account. Pass `allowed_projects` to restrict the group to specific projects (empty/absent = org-wide).


        **Required permissions:** Any of `account:admin`, `account:group:manage`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters: []
      responses:
        '200':
          description: The created user group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:admin
      - account:group:manage
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/groups.ts
        className: UserGroupsResource
        methodName: create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserGroupPayload'
  /iam/groups/sync-members:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    post:
      operationId: SyncMembersUserGroup
      tags:
      - User Groups
      summary: Sync the members group
      description: 'Synchronizes the built-in members group with current account membership.


        **Required permissions:** Any of `account:admin`, `account:group:manage`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters: []
      responses:
        '200':
          description: The synchronized members group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:admin
      - account:group:manage
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/groups.ts
        className: UserGroupsResource
        methodName: syncMembers
  /iam/groups/{groupId}:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    put:
      operationId: UpdateUserGroup
      tags:
      - User Groups
      summary: Update a user group
      description: 'Updates a user group by ID.


        **Required permissions:** Any of `account:admin`, `account:group:manage`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters:
      - name: groupId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated user group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:admin
      - account:group:manage
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/groups.ts
        className: UserGroupsResource
        methodName: update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserGroupPayload'
    get:
      operationId: GetUserGroup
      tags:
      - User Groups
      summary: Retrieve a user group
      description: 'Retrieves a user group by ID.


        **Required permissions:** Any of `account:read`, `account:group:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:read
      parameters:
      - name: groupId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested user group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:read
      - account:group:read
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/groups.ts
        className: UserGroupResource
        methodName: doGet
  /iam/groups/{groupId}/members:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    get:
      operationId: ListUserGroupMembers
      tags:
      - User Groups
      summary: List user group members
      description: 'Lists members of a user group.


        **Required permissions:** Any of `account:read`, `account:group:read`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:read
      parameters:
      - name: groupId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User group members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRefArray'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:read
      - account:group:read
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/groups.ts
        className: UserGroupResource
        methodName: listMembers
  /iam/groups/{groupId}/members/{userId}:
    parameters:
    - name: x-api-version
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        pattern: \S
        example: '20260803'
      description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
      x-vertesia-global-header: true
    post:
      operationId: AddUserGroupMember
      tags:
      - User Groups
      summary: Add a user to a group
      description: 'Adds a user to a user group.


        **Required permissions:** Any of `account:admin`, `account:group:manage`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters:
      - name: groupId
        in: path
        required: true
        schema:
          type: string
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated user group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:admin
      - account:group:manage
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/groups.ts
        className: UserGroupResource
        methodName: addMember
    delete:
      operationId: RemoveUserGroupMember
      tags:
      - User Groups
      summary: Remove a user from a group
      description: 'Removes a user from a user group.


        **Required permissions:** Any of `account:admin`, `account:group:manage`'
      security:
      - bearerAuth: []
      - OAuth2:
        - account:admin
      parameters:
      - name: groupId
        in: path
        required: true
        schema:
          type: string
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The updated user group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions:
      - account:admin
      - account:group:manage
      x-vertesia-source:
        file: ../../apps/studio-server/src/api/iam/groups.ts
        className: UserGroupResource
        methodName: removeMember
components:
  schemas:
    UserRefArray:
      type: array
      items:
        $ref: '#/components/schemas/UserRef'
    UserGroup:
      type: object
      properties:
        id:
          type: string
        account:
          type: string
        name:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        created_by:
          type: string
        updated_by:
          type: string
        properties:
          type: object
          additionalProperties: true
          description: Custom properties for dynamic permission matching
        clearance:
          type: number
          description: BLP clearance level — merged with user clearance using max()
        compartments:
          type: array
          items:
            type: string
          description: Compartments — merged with user compartments using array union
        allowed_projects:
          type: array
          items:
            type: string
          description: Projects this group is allowed to be used in. When empty or absent the group is org-wide (usable in any project). When set, the group may only be used to grant permissions in the listed projects.
        member_count:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Number of users in the group. Returned by the group listing only.
      required:
      - id
      - account
      - name
      - tags
      - created_at
      - updated_at
      additionalProperties: false
    UpdateUserGroupPayload:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        properties:
          type: object
          additionalProperties: true
          description: Custom properties for dynamic permission matching
        clearance:
          type: number
          description: BLP clearance level — merged with user clearance using max()
        compartments:
          type: array
          items:
            type: string
          description: Compartments — merged with user compartments using array union
        allowed_projects:
          type: array
          items:
            type: string
          description: Projects this group is allowed to be used in. When empty or absent the group is org-wide (usable in any project). When set, the group may only be used to grant permissions in the listed projects.
      required:
      - name
      additionalProperties: false
    UserRef:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
        picture:
          type: string
      required:
      - id
      - name
      - email
      additionalProperties: false
    UserGroupArray:
      type: array
      items:
        $ref: '#/components/schemas/UserGroup'
    ErrorResponse:
      type: object
      description: Standard JSON error response returned by the server error handler.
      properties:
        error:
          type: string
          description: HTTP status text or normalized error type.
        status:
          type: integer
          format: int32
          minimum: 400
          maximum: 599
          description: HTTP status code. Client errors use a 4xx status code; server errors use 500.
          example: 400
        message:
          type: string
          description: Human-readable error message.
        details:
          type: string
          description: Optional additional error details.
        errorCode:
          type: string
          description: Machine-readable code for the specific failure, present when the error carries one, so clients can branch on it without parsing `message`.
          example: account_api_key_creation_disabled
      required:
      - error
      - status
      additionalProperties: false
    CreateUserGroupPayload:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        allowed_projects:
          type: array
          items:
            type: string
          description: Restrict the new group to the given projects (empty/absent = org-wide).
      required:
      - name
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://cloud.us1.vertesia.io/oauth/authorize
          tokenUrl: https://sts.vertesia.io/oauth/token
          x-scalar-security-query:
            resource: https://api.us1.vertesia.io/api/v1
          x-scalar-security-body:
            resource: https://api.us1.vertesia.io/api/v1
          scopes:
            openid: ''
            profile: ''
            offline_access: ''
            interaction:read: ''
            interaction:write: ''
            interaction:delete: ''
            interaction:execute: ''
            run:read: ''
            run:write: ''
            environment:admin: ''
            app:manage: ''
            project:admin: ''
            project:integration_read: ''
            project:settings_write: ''
            api_key:read: ''
            account:read: ''
            account:write: ''
            account:admin: ''
            audit:read: ''
            account:member: ''
            content:read: ''
            content:read_all: ''
            content:write: ''
            content:delete: ''
            content:admin: ''
            content:superadmin: ''
            workflow:read: ''
            workflow:run: ''
            workflow:admin: ''
            workflow:superadmin: ''
            agent_run:read: ''
            task:read: ''
            task:manage: ''
x-tagGroups:
- name: Authentication
  tags:
  - Token Service
- name: GenAI
  tags:
  - Environments
  - Prompt Templates
  - Interactions
  - Interaction Runs
  - Agent Runs
- name: Content
  tags:
  - Content Object Types
  - Objects
  - Collections
  - Files
  - Rendering
  - Bulk Operations
  - Commands
- name: Data Store
  tags:
  - Data
- name: Workflow
  tags:
  - Processes
  - Tasks
  - Workflow Definitions
  - Workflow Rules
  - Workflow Runs
- name: Administration
  tags:
  - Accounts
  - Projects
  - Audit Trail
  - Costs
- name: Access Control
  tags:
  - Users
  - User Groups
  - Roles
  - Access Control Entries
  - API Keys
- name: Apps & Integrations
  tags:
  - Apps
  - OAuth Providers
  - OAuth Clients
  - OAuth Grants
  - Remote MCP Connections