Charthop user API

openapi: 3.2.0
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access User API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: user
paths:
  /v1/user:
    get:
      tags:
      - user
      summary: Return all users within an org or across orgs
      operationId: findUsers
      parameters:
      - name: orgId
        in: query
        description: Org id to search within
        required: false
        schema:
          type: string
      - name: ids
        in: query
        description: List of user ids to look up
        required: false
        schema:
          type: string
      - name: from
        in: query
        description: User id to start from
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: sort
        in: query
        description: 'Sort by: id, name, email, inviteStatus, activeAt, updateAt. Prepend - for descending (e.g. -activeAt). Without orgId (cross-org admin only), ''activeAt'' takes the legacy iterateAllActive path.'
        required: false
        schema:
          type: string
      - name: q
        in: query
        description: Substring search across name (first/last/preferred) and email
        required: false
        schema:
          type: string
      - name: inviteStatus
        in: query
        description: 'Filter by invite status: JOINED (user has logged in) or INVITED (not yet logged in). NOT_INVITED is not valid here — by definition findUsers returns only users with accounts.'
        required: false
        schema:
          type: string
          enum:
          - INVITED
          - JOINED
          - NOT_INVITED
      - name: roleId
        in: query
        description: Custom role id to filter by. Requires orgId.
        required: false
        schema:
          type: string
      - name: returnAccess
        in: query
        description: Return access information -- pass a comma-separated list of actions to check (e.g. update,delete). Requires orgId.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsUser'
        '400':
          description: bad request
        '404':
          description: not found
    post:
      tags:
      - user
      summary: Create a new user
      operationId: createUser
      responses:
        '201':
          description: user created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
        description: User data to create
        required: true
  /v1/user/assign:
    patch:
      tags:
      - user
      summary: Assign or remove multiple users a role within an org
      operationId: assignUsers
      responses:
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/UpdateUser'
        description: User data
        required: true
  /v1/user/count:
    get:
      tags:
      - user
      summary: Count users matching the same filters as findUsers, broken down by invite status
      operationId: countUsers
      parameters:
      - name: orgId
        in: query
        description: Org id to count within
        required: true
        schema:
          type: string
      - name: q
        in: query
        description: Substring search across name (first/last/preferred) and email
        required: false
        schema:
          type: string
      - name: inviteStatus
        in: query
        description: 'Filter by invite status: JOINED or INVITED. NOT_INVITED is not valid.'
        required: false
        schema:
          type: string
          enum:
          - INVITED
          - JOINED
          - NOT_INVITED
      - name: roleId
        in: query
        description: Custom role id to filter by
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCount'
        '400':
          description: bad request
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/user/email/{email}:
    get:
      tags:
      - user
      summary: Return a particular user by email
      operationId: getUserByEmail
      parameters:
      - name: email
        in: path
        description: Email
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: bad request
        '404':
          description: not found
  /v1/user/invite:
    post:
      tags:
      - user
      summary: Create/invite multiple new users
      operationId: createUsers
      responses:
        '201':
          description: users created
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateUser'
        description: User data to create
        required: true
  /v1/user/login/{email}:
    get:
      tags:
      - user
      summary: Return the login options for a user
      operationId: getUserLoginOption
      parameters:
      - name: email
        in: path
        description: User email
        required: true
        schema:
          type: string
      - name: orgSlug
        in: query
        description: Org slug
        required: false
        schema:
          type: string
      responses:
        '200':
          description: login options returned
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
  /v1/user/me:
    get:
      tags:
      - user
      summary: Return the currently logged in user
      operationId: getMe
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: unauthorized
  /v1/user/me/view:
    get:
      tags:
      - user
      summary: Return the user the user is currently viewing as
      operationId: getMeView
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: unauthorized
  /v1/user/person/{personId}:
    get:
      tags:
      - user
      summary: Return a particular user by its corresponding person id
      operationId: getUserByPersonId
      parameters:
      - name: personId
        in: path
        description: Person id to fetch user for
        required: true
        schema:
          type: string
      - name: orgId
        in: query
        description: Org id to search within
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: bad request
        '404':
          description: not found
  /v1/user/sendreset:
    post:
      tags:
      - user
      summary: Send a password reset email
      operationId: sendResetEmail
      responses:
        '204':
          description: email sent
        '400':
          description: email not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailRequest'
        description: User email address
        required: true
  /v1/user/token:
    delete:
      tags:
      - user
      summary: Revoke multiple user's access tokens
      operationId: revokeUsersTokens
      responses:
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                example: 588f7ee98f138b19220041a7
        description: User ids
        required: true
  /v1/user/{userId}:
    get:
      tags:
      - user
      summary: Return a particular user by id
      operationId: getUser
      parameters:
      - name: userId
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: bad request
        '404':
          description: not found
    patch:
      tags:
      - user
      summary: Update an existing user
      operationId: updateUser
      parameters:
      - name: userId
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: user updated
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUser'
        description: User data to update
        required: true
  /v1/user/{userId}/password:
    post:
      tags:
      - user
      summary: Change a user's password, or switch a user to SSO
      operationId: changePassword
      parameters:
      - name: userId
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: password changed
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePasswordRequest'
        required: true
  /v1/user/{userId}/token:
    delete:
      tags:
      - user
      summary: Revoke a user's access token
      operationId: revokeUserToken
      parameters:
      - name: userId
        in: path
        description: User id
        required: true
        schema:
          type: string
      responses:
        '401':
          description: unauthorized
        '404':
          description: not found
  /v2/user/invite:
    post:
      tags:
      - user
      summary: Create/invite multiple new users
      operationId: inviteUsersToOrg
      responses:
        '200':
          description: users created
          content:
            application/json:
              schema:
                type: array
                uniqueItems: true
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteUsersRequest'
        required: true
components:
  schemas:
    ChangePasswordRequest:
      type: object
      required:
      - newPassword
      properties:
        newPassword:
          type: string
          description: password to change to
        oldPassword:
          type: string
          description: password to change from
    CreateUser:
      type: object
      required:
      - orgs
      properties:
        appId:
          type: string
          description: if the user is an app user, the id of the app
          example: 588f7ee98f138b19220041a7
        name:
          description: full name of user
          $ref: '#/components/schemas/Name'
        email:
          type: string
          description: email address of user
          example: bob@example.com
          minItems: 0
          maxItems: 120
        orgs:
          type: array
          description: list of member orgs with permission levels
          uniqueItems: true
          items:
            $ref: '#/components/schemas/OrgAccess'
        imagePath:
          type: string
          description: path to full-sized profile image in storage
          pattern: ^[a-zA-Z0-9._/-]+$
        status:
          type: string
          description: current status of user
          enum:
          - SUPERUSER
          - NORMAL
          - INACTIVE
          - UNINSTALLED
        type:
          type: string
          description: type of user
          enum:
          - USER
          - APP
        options:
          type: object
          description: for apps, options (specific options are specific to the particular app); for users, user-set preferences
        internalOptions:
          type: object
          description: internal (ChartHop controlled) options
        secrets:
          type: object
          description: write-only secrets; the content of these secrets are not retrievable via the external-facing API
        emailSettings:
          type: array
          description: Email settings for the user
          items:
            $ref: '#/components/schemas/UserEmailSetting'
        sensitive:
          type: string
          description: sensitivity level of the user's configuration; only applicable to APP users
          enum:
          - GLOBAL
          - ORG
          - SENSITIVE
          - PERSONAL
          - MANAGER
          - HIGH
          - PRIVATE
        shareAccess:
          type: array
          description: users and groups who have access to configure this user; only applicable to APP users
          items:
            $ref: '#/components/schemas/ShareAccess'
        agentConfig:
          description: per-user agent configuration overrides
          $ref: '#/components/schemas/AiAgentConfig'
    ResultsUser:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        next:
          type: string
        access:
          type: array
          items:
            $ref: '#/components/schemas/ResultsAccess'
    TargetedInstruction:
      type: object
      required:
      - filter
      - instructions
      properties:
        filter:
          type: string
          description: filter expression matched against the current viewer's person record
        instructions:
          type: string
          description: instructions injected into the chat prompt when filter matches
    PolicyRule:
      type: object
      properties:
        allow:
          type: array
          description: allow rules
          example: '[''job:read'', ''person.read'']'
          items:
            type: string
        deny:
          type: array
          description: deny rules
          example: '[''job:read'', ''person.read'']'
          items:
            type: string
        categories:
          type: array
          description: categories the rule is limited to
          example: '[''Compensation'', ''Stock Grants'']'
          items:
            type: string
        fields:
          type: array
          description: fields the rule is limited to
          example: '[''base'']'
          items:
            type: string
        departmentIds:
          type: array
          description: departments the rule is limited to
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        filter:
          type: string
          description: custom filter the rule is limited to
          example: department:engineering and under:me
        directions:
          type: array
          description: directions that the rule applies to -- either self or under
          items:
            type: string
        types:
          type: array
          description: types that the rule applies to
          items:
            type: string
        targets:
          type: array
          description: targets allowed for messaging (email addresses, chat channels, user ids)
          items:
            $ref: '#/components/schemas/PolicyRuleTarget'
        visibleSensitive:
          type: array
          description: if specified, controls visibility of sensitive entities -- for example, ['Manager Shared', 'Manager Only']
          items:
            type: string
        fieldsSensitive:
          type: array
          description: if specified, controls applicability of fields by sensitivity -- for example, ['Manager Shared', 'Manager Only']
          items:
            type: string
    UserCount:
      type: object
      required:
      - totalCount
      - joinedCount
      - invitedCount
      properties:
        totalCount:
          type: integer
          format: int64
        joinedCount:
          type: integer
          format: int64
        invitedCount:
          type: integer
          format: int64
    ShareAccess:
      type: object
      required:
      - access
      properties:
        access:
          type: string
          description: access permission level
          enum:
          - NONE
          - LIMITED_READ
          - LIMITED_WRITE
          - STANDARD_READ
          - STANDARD_WRITE
          - COMPENSATION_READ
          - FULL_READ
          - COMP_PLANNING_PARTICIPANT
          - COMPENSATION_WRITE
          - WRITE
          - COMPENSATION_OWNER
          - OWNER
        userId:
          type: string
          description: user id
          example: 5887a7718f138b6a2a0041a7
        groupId:
          type: string
          description: group id
          example: 5887a7718f138b6a2a0041a7
        fields:
          type: string
          description: fields
          example: name,image,title
    AiAgentConfig:
      type: object
      properties:
        personality:
          type: string
        instructions:
          type: string
        guardrails:
          type: string
        enableMemory:
          type: boolean
        enableMcpServer:
          type: boolean
          description: whether this agent exposes an MCP server endpoint for per-user OAuth access
        enableMcpWrite:
          type: boolean
          description: 'whether this agent''s MCP server may invoke write/mutating tools (e.g. a non-read-only AskAgent delegation). Read-only by default: when unset or false, a tool that mutates on the call is rejected at the MCP edge regardless of the agent''s role/policy. This is defense in depth layered on top of the role, never a grant beyond it.'
        isExternal:
          type: boolean
          description: 'whether this agent is an external (non-ChartHop) client, e.g. Claude Code or ChatGPT. External agents have no ChartHop-side prompt/behavior config: only permissions, MCP, and activity are configurable.'
        approvedPolicyRules:
          type: array
          items:
            $ref: '#/components/schemas/PolicyRule'
        approvalGuidelines:
          type: string
        managerJobId:
          type: string
          example: 588f7ee98f138b19220041a7
        messagingConfig:
          $ref: '#/components/schemas/MessagingConfig'
        contentIds:
          type: array
          description: pinned content document IDs; when merging user and app configs, both lists are unioned (not replaced); validate with validateContentIds before persisting
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        modelTier:
          type: string
          description: requested model tier for the agent; defaults to MEDIUM when not set
          enum:
          - HIGH
          - MEDIUM
          - LOW
        targetedInstructions:
          type: array
          description: audience-scoped instruction snippets injected into the chat prompt when the filter matches the current viewer's person record; size and filter syntax are checked by AgentValidationService before persisting
          items:
            $ref: '#/components/schemas/TargetedInstruction'
    ResultsAccess:
      type: object
      required:
      - allowed
      properties:
        ids:
          type: array
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        allowed:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/AccessAction'
    InviteUsersRequest:
      type: object
      required:
      - createUsers
      properties:
        createUsers:
          type: array
          items:
            $ref: '#/components/schemas/CreateUser'
        emailSettings:
          $ref: '#/components/schemas/WelcomeEmailSettings'
    UserEmailSetting:
      type: object
      required:
      - category
      - subscribed
      properties:
        category:
          type: string
          description: Category of emails
          example: ADMINISTRATIVE
          enum:
          - ADMINISTRATIVE
          - BILLING
          - DATA_IMPORT_AND_SYNC_STATUS
          - TRIAL_REMINDERS
          - APPROVAL_NOTIFICATIONS
        subscribed:
          type: boolean
          description: Is user subscribed to the category of emails
    MessagingConfig:
      type: object
      properties:
        slackAppId:
          type: string
        slackClientId:
          type: string
        slackBotUserId:
          type: string
    UpdateUser:
      type: object
      properties:
        appId:
          type: string
          description: if the user is an app user, the id of the app
          example: 588f7ee98f138b19220041a7
        name:
          description: full name of user
          $ref: '#/components/schemas/Name'
        email:
          type: string
          description: email address of user
          example: bob@example.com
          minItems: 0
          maxItems: 120
        orgs:
          type: array
          description: list of member orgs with permission levels
          uniqueItems: true
          items:
            $ref: '#/components/schemas/OrgAccess'
        imagePath:
          type: string
          description: path to full-sized profile image in storage
          pattern: ^[a-zA-Z0-9._/-]+$
        status:
          type: string
          description: current status of user
          enum:
          - SUPERUSER
          - NORMAL
          - INACTIVE
          - UNINSTALLED
        options:
          type: object
          description: for apps, options (specific options are specific to the particular app); for users, user-set preferences
        internalOptions:
          type: object
          description: internal (ChartHop controlled) options
        secrets:
          type: object
          description: write-only secrets; the content of these secrets are not retrievable via the external-facing API
        emailSettings:
          type: array
          description: Email settings for the user
          items:
            $ref: '#/components/schemas/UserEmailSetting'
        sensitive:
          type: string
          description: sensitivity level of the user's configuration; only applicable to APP users
          enum:
          - GLOBAL
          - ORG
          - SENSITIVE
          - PERSONAL
          - MANAGER
          - HIGH
          - PRIVATE
        shareAccess:
          type: array
          description: users and groups who have access to configure this user; only applicable to APP users
          items:
            $ref: '#/components/schemas/ShareAccess'
        agentConfig:
          description: per-user agent configuration overrides
          $ref: '#/components/schemas/AiAgentConfig'
    AccessAction:
      type: object
      required:
      - action
      properties:
        action:
          type: string
        fields:
          type: array
          uniqueItems: true
          items:
            type: string
        types:
          type: array
          uniqueItems: true
          items:
            type: string
    Name:
      type: object
      required:
      - last
      properties:
        first:
          type: string
          description: first name
          example: Jane
          minItems: 0
          maxItems: 80
        middle:
          type: string
          description: middle name
          example: Quidditch
          minItems: 0
          maxItems: 80
        last:
          type: string
          description: last name
          example: Public
          minItems: 0
          maxItems: 80
        pref:
          type: string
          description: preferred first name
          example: JQ
          minItems: 0
          maxItems: 80
        prefLast:
          type: string
          description: preferred last name
          example: Smith
          minItems: 0
          maxItems: 80
    PolicyRuleTarget:
      type: object
      properties:
        userId:
          type: string
        personId:
          type: string
          example: 588f7ee98f138b19220041a7
        channel:
          type: string
        email:
          type: string
    BundleInstall:
      type: object
      required:
      - entities
      properties:
        entities:
          type: array
          items:
            $ref: '#/components/schemas/BundleInstallEntity'
    Attribution:
      type: object
      properties:
        principalUserId:
          type: string
          example: 588f7ee98f138b19220041a7
        agentUserIds:
          type: array
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        eventId:
          type: string
          example: 588f7ee98f138b19220041a7
        aiChatId:
          type: string
          example: 588f7ee98f138b19220041a7
        aiToolUseId:
          type: string
        channel:
          type: string
          enum:
          - WEB
          - MOBILE
          - SLACK
          - TEAMS
          - MCP
    WelcomeEmailSettings:
      type: object
      required:
      - isEnabled
      - welcomeEmailSubject
      - welcomeEmailButtonLabel
      - welcomeEmailBody
      properties:
        isEnabled:
          type: boolean
          description: Whether to send a welcome email
        welcomeEmailSubject:
          type: string
          description: Subject
        welcomeEmailButtonLabel:
          type: string
          description: Button label
        welcomeEmailBody:
          type: string
          description: Body
    User:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        appId:
          type: string
          description: if the user is an app user, the id of the app
          example: 588f7ee98f138b19220041a7
        name:
          description: full name of user
          $ref: '#/components/schemas/Name'
        email:
          type: string
          description: email address of user
          example: bob@example.com
          minItems: 0
          maxItems: 120
        password:
          type: string
          description: password of user (encrypted)
          minItems: 0
          maxItems: 120
        orgs:
          type: array
          description: list of member orgs with permission levels
          uniqueItems: true
          items:
            $ref: '#/components/schemas/OrgAccess'
        imagePath:
          type: string
          description: path to full-sized profile image in storage
          pattern: ^[a-zA-Z0-9._/-]+$
        status:
          type: string
          description: current status of user
          enum:
          - SUPERUSER
          - NORMAL
          - INACTIVE
          - UNINSTALLED
        type:
          type: string
          description: type of user
          enum:
          - USER
          - APP
        options:
          type: object
          description: for apps, options (specific options are specific to the particular app); for users, user-set preferences
        internalOptions:
          type: object
          description: internal (ChartHop controlled) options
        bundleInstall:
          description: if this user represents an installed bundle, details on what was installed
          $ref: '#/components/schemas/BundleInstall'
        secrets:
          type: object
          description: write-only secrets; the content of these secrets are not retrievable via the external-facing API
        activeAt:
          type: string
          description: last activity timestamp
          example: '2017-01-24T13:57:52Z'
        loginAt:
          type: string
          description: last login timestamp
          example: '2017-01-24T13:57:52Z'
        appRunCheckAt:
          type: string
          description: for apps, last time the app was checked for a scheduled sync
          example: '2024-02-29T09:30:00Z'
        loginCount:
          type: integer
          format: int32
          description: number of lifetime successful logins
          example: '3'
        sessionCount:
          type: integer
          format: int32
          description: number of lifetime sessions
          example: '3'
        loginFailCount:
          type: integer
          format: int32
          description: number of consecutive failed logins
          example: '3'
        title:
          type: string
          description: job title, if available
          example: CEO
        remoteIp:
          type: string
          description: last IP address used
          example: 127.0.0.1
        createId:
          type: string
          description: created by user id
          example: 588f7ee98f138b19220041a7
        createBehalfId:
          type: string
          description: created on behalf of user id
          example: 588f7ee98f138b19220041a7
        createAttribution:
          $ref: '#/components/schemas/Attribution'
        createAt:
          type: string
          description: created timestamp
          example: '2017-01-24T13:57:52Z'
        updateId:
          type: string
          description: last updated by user id
          example: 588f7ee98f138b19220041a7
        updateBehalfId:
          type: string
          description: last updated on behalf of user id
          example: 588f7ee98f138b19220041a7
        updateAttribution:
          $ref: '#/components/schemas/Attribution'
        updateAt:
          type: string
          description: last updated timestamp
          example: '2017-01-24T13:57:52Z'
        verifyAt:
          type: string
          description: email verified timestamp, if the email ha

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/charthop/refs/heads/main/openapi/charthop-user-api-openapi.yml