Charthop app API

swagger: '2.0'
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access app API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
host: localhost
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: app
paths:
  /v1/app:
    get:
      tags:
      - app
      summary: Return all publicly visible global apps
      operationId: findGlobalApps
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: tag
        in: query
        description: Tag to filter by
        required: false
        type: string
      - name: from
        in: query
        description: App id to start from
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        type: integer
        format: int32
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsApp'
        '400':
          description: bad request
        '404':
          description: not found
    post:
      tags:
      - app
      summary: Create a new app
      operationId: createApp
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: body
        in: body
        description: App data to create
        required: true
        schema:
          $ref: '#/definitions/CreateApp'
      responses:
        '201':
          description: app created
          schema:
            $ref: '#/definitions/App'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
  /v1/app/install/{appId}:
    get:
      tags:
      - app
      summary: Get all active installs of this app
      operationId: getActiveAppInstalls
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: appId
        in: path
        description: App id
        required: true
        type: string
      - name: orgTypes
        in: query
        description: Comma-separated list of org types to include. Defaults to all org types.
        required: false
        type: string
      - name: hasRunProcess
        in: query
        description: Whether to require that the app has run at least one process. Defaults to true.
        required: false
        type: boolean
      - name: internalOptions
        in: query
        description: Filter app users by internal option key-value pair
        required: false
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsUser'
  /v1/app/name/{appName}:
    get:
      tags:
      - app
      summary: Return a particular app by name
      operationId: getAppByName
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: appName
        in: path
        description: App name
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/App'
        '400':
          description: bad request
        '404':
          description: not found
  /v1/app/notify:
    post:
      tags:
      - app
      summary: Send an email notification to the configured notify users, on behalf of an app
      operationId: sendNotification
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/NotifyRequest'
      responses:
        '204':
          description: notification sent
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/app/org/{orgId}:
    get:
      tags:
      - app
      summary: Return all active apps available for a particular org
      operationId: findApps
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: q
        in: query
        description: Search query
        required: false
        type: string
      - name: type
        in: query
        description: Filter by type (app, bundle)
        required: false
        type: string
      - name: tags
        in: query
        description: Filter by tags
        required: false
        type: string
      - name: from
        in: query
        description: App id to start from
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        type: integer
        format: int32
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsApp'
        '400':
          description: bad request
        '404':
          description: not found
  /v1/app/org/{orgId}/install:
    get:
      tags:
      - app
      summary: Find installed app users
      operationId: findInstalledApps
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: type
        in: query
        description: Filter by type (app, bundle)
        required: false
        type: string
      - name: tags
        in: query
        description: Filter by tag
        required: false
        type: string
      - name: statuses
        in: query
        description: 'Filter by App User statuses, comma-separated. Accepted values: [''NORMAL'', ''INACTIVE'', ''UNINSTALLED'']'
        required: false
        type: string
      - name: includeFormer
        in: query
        description: Whether to include app users with NONE access to orgs they pertain to.  Default is false
        required: false
        type: boolean
      - name: from
        in: query
        description: App id to start from
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        type: integer
        format: int32
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsUser'
        '400':
          description: bad request
        '404':
          description: not found
    post:
      tags:
      - app
      summary: Install an app for a particular org
      operationId: installApp
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: App user data to create
        required: true
        schema:
          $ref: '#/definitions/CreateUser'
      responses:
        '201':
          description: app installed
          schema:
            $ref: '#/definitions/User'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
  /v1/app/org/{orgId}/install/name/{appName}:
    get:
      tags:
      - app
      summary: Get an installed app by name
      operationId: getInstalledAppByName
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appName
        in: path
        description: App name
        required: true
        type: string
      - name: includeInactive
        in: query
        description: If the installed appUser is inactive, load inactive instead
        required: false
        type: boolean
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/User'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/app/org/{orgId}/install/validate:
    post:
      tags:
      - app
      summary: Validate the installation of an app for a particular org
      operationId: validateInstallApp
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: App user data to create
        required: true
        schema:
          $ref: '#/definitions/CreateUser'
      responses:
        '201':
          description: app validated
          schema:
            $ref: '#/definitions/BundleInstallValidate'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
  /v1/app/org/{orgId}/install/{appUserId}:
    get:
      tags:
      - app
      summary: Get an installed app
      operationId: getInstalledApp
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/User'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    patch:
      tags:
      - app
      summary: Update the settings of an installed app
      operationId: updateInstalledApp
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      - name: body
        in: body
        description: App user data to update
        required: true
        schema:
          $ref: '#/definitions/UpdateUser'
      - name: includeInactive
        in: query
        description: If the installed appUser is inactive, load inactive instead
        required: false
        type: boolean
      responses:
        '204':
          description: app updated
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    delete:
      tags:
      - app
      summary: Uninstall an app
      operationId: uninstallApp
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      - name: keepEntityIds
        in: query
        description: Comma-separated list of bundle-installed entities to delete -- if this parameter is omitted, all bundle-installed entities will be deleted
        required: false
        type: string
      responses:
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/app/org/{orgId}/install/{appUserId}/api-operation/{operation}:
    post:
      tags:
      - app
      summary: Execute one configured external API operation against the live external service (the app config 'Test' action). Requires readExternal for a read-only operation, writeExternal otherwise; a non-read-only operation runs against the live API and may create, change, or delete real data.
      operationId: testApiOperation
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      - name: operation
        in: path
        description: Operation id
        required: true
        type: string
      - name: from
        in: query
        description: Pagination cursor (opaque 'next' from a prior result)
        required: false
        type: string
      - name: limit
        in: query
        description: Maximum number of records to return
        required: false
        type: integer
        format: int32
      - name: tokenLevel
        in: query
        description: 'OAuth identity to call as: USER (caller''s own connection) or ORG (shared connection). Defaults to the installation''s mode.'
        required: false
        type: string
        enum:
        - ORG
        - USER
      - name: body
        in: body
        required: false
        schema:
          type: object
          additionalProperties:
            type: object
      responses:
        '200':
          description: operation executed (inspect the result for the API's status/body)
          schema:
            $ref: '#/definitions/ExternalApiExecutionResult'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/app/org/{orgId}/install/{appUserId}/code:
    post:
      tags:
      - app
      summary: Retrieve an Oauth2 authorization code for this app, which can be exchanged for an access token
      operationId: getAuthorizationCode
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      - name: scope
        in: query
        description: Scopes
        required: false
        type: string
      responses:
        '201':
          description: successful operation
          schema:
            $ref: '#/definitions/AccessTokenResponse'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/app/org/{orgId}/install/{appUserId}/connections:
    get:
      tags:
      - app
      summary: List an installed agent's active MCP connections (one per connected user token)
      operationId: listMcpConnections
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      responses:
        '200':
          description: successful operation
        '403':
          description: permission denied
        '404':
          description: not found
    delete:
      tags:
      - app
      summary: Revoke MCP connections for an installed agent
      operationId: revokeMcpConnections
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/RevokeMcpConnectionsRequest'
      responses:
        '204':
          description: revoked
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/app/org/{orgId}/install/{appUserId}/disable-sync:
    post:
      tags:
      - app
      summary: Disable automatic sync for an app installation whose credentials are failing
      operationId: disableSync
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/DisableSyncRequest'
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/DisableSyncResponse'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/app/org/{orgId}/install/{appUserId}/installdata/{installDataName}:
    get:
      tags:
      - app
      summary: Retrieve the current token for this app
      operationId: getAppInstallData
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      - name: installDataName
        in: path
        description: Name
        required: true
        type: string
      responses:
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/app/org/{orgId}/install/{appUserId}/oauth-token/refresh:
    post:
      tags:
      - app
      summary: Force-refresh the vendor OAuth token for an app installation
      operationId: refreshOauthToken
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/OauthRefreshRequest'
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/OauthRefreshResponse'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: no active token / refresh failed — re-authorization required
  /v1/app/org/{orgId}/install/{appUserId}/run:
    post:
      tags:
      - app
      summary: Run an installed app
      operationId: runInstalledApp
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      - name: body
        in: body
        required: false
        schema:
          type: object
          additionalProperties:
            type: object
      responses:
        '200':
          description: app started
          schema:
            $ref: '#/definitions/Process'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/app/org/{orgId}/install/{appUserId}/token:
    get:
      tags:
      - app
      summary: Retrieve the current token for this app
      operationId: getAccessToken
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/AccessTokenResponse'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    post:
      tags:
      - app
      summary: Generate or regenerate a long-lived access token for the app
      operationId: generateAccessToken
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        type: string
      - name: body
        in: body
        required: true
        schema:
          $ref: '#/definitions/ScopeRequest'
      responses:
        '201':
          description: successful operation
          schema:
            $ref: '#/definitions/AccessTokenResponse'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/app/{appId}:
    get:
      tags:
      - app
      summary: Return a particular app by id
      operationId: getApp
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: appId
        in: path
        description: App id
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/App'
        '400':
          description: bad request
        '404':
          description: not found
    patch:
      tags:
      - app
      summary: Update an existing app
      operationId: updateApp
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: appId
        in: path
        description: App id
        required: true
        type: string
      - name: body
        in: body
        description: App data to update
        required: true
        schema:
          $ref: '#/definitions/UpdateApp'
      responses:
        '204':
          description: app updated
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    delete:
      tags:
      - app
      summary: Delete an app
      operationId: deleteApp
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: appId
        in: path
        description: App id
        required: true
        type: string
      responses:
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
definitions:
  ActionStep:
    type: object
    required:
    - type
    properties:
      stepId:
        type: string
        description: unique id for action step
        example: 588f7ee98f138b19220041a7
      type:
        type: string
        description: The type of action to run
        enum:
        - FORM
        - MESSAGE
        - HTTP
        - TASK
        - SIGNATURE
        - AI
      formId:
        type: string
        description: If the action is FORM, the id of the form to fill out
        example: 588f7ee98f138b19220041a7
      target:
        type: string
        description: If the action is MESSAGE, the target to send the message to. If the action is FORM/TASK, the person who should have the form filled out on/complete the task
      assignee:
        type: string
        description: If the action is FORM/TASK, the user who should fill out the form/complete the task (default is, same as target)
      notifyTarget:
        type: string
        description: If the action is SIGNATURE, an additional target expression resolving to users who should receive notifications about signature events
      templateId:
        type: string
        description: If the action is SIGNATURE, the id of the template to generate a document for signature
        example: 588f7ee98f138b19220041a7
      aiAgentUserId:
        type: string
        description: If the action is AI, the agent id to use, otherwise defaults to org default
        example: 588f7ee98f138b19220041a7
      aiEnableMemory:
        type: boolean
        description: If the action is AI, whether or not a per-action memory storage is supported
      aiApprovedPolicyRules:
        type: array
        description: If the action is AI, the policy rules that the AI agent should follow. If not provided, will use the default policy rules for the AI agent.
        items:
          $ref: '#/definitions/PolicyRule'
      modelTier:
        type: string
        description: If the action is AI, the requested model tier; defaults to LOW when not set
        enum:
        - HIGH
        - MEDIUM
        - LOW
      message:
        type: string
        description: The message that will be sent -- supports CQLT templates
      messageChannel:
        description: The preferred message channel(s) to send via
        $ref: '#/definitions/MessageChannelConfig'
      emailSubject:
        type: string
        description: The email subject line that will be used -- supports CQLT templates. If not provided, will use 'Notification'
      taskLabel:
        type: string
        description: If the action is FORM, the task label that will be displayed to the user -- supports CQLT templates
      sensitive:
        type: boolean
        description: whether to run with access to sensitive events or not - if this is left blank, will default to the sensitive setting of the Action
      httpUrl:
        type: string
        format: uri
        description: If the action is HTTP, the url that will receive the HTTP request
      httpMethod:
        type: string
        description: If the action is HTTP, the method used by the HTTP request (defaults to POST)
      httpHeaders:
        type: object
        description: If the action is HTTP, the headers to add to the HTTP request
        additionalProperties:
          type: string
      httpContent:
        type: object
        description: If the action is HTTP, the payload contained in the HTTP request
  PaginationConfig:
    type: object
    required:
    - type
    properties:
      type:
        type: string
        enum:
        - NONE
        - NEXT_URL
        - LINK_HEADER
        - CURSOR
        - OFFSET
        - PAGE_NUMBER
      itemsPath:
        type: string
      nextPath:
        type: string
      hasMorePath:
        type: string
      endOfStreamPath:
        type: string
      totalPath:
        type: string
      linkRel:
        type: string
      pageParam:
        type: string
      sizeParam:
        type: string
      pageSize:
        type: integer
        format: int32
      startValue:
        type: integer
        format: int32
  GroupPositionAssignments:
    type: object
    required:
    - values
    properties:
      values:
        type: object
        additionalProperties:
          type: array
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
  BundleReport:
    type: object
    required:
    - report
    properties:
      report:
        description: report of this bundle
        $ref: '#/definitions/PartialReport'
      charts:
        type: array
        description: list of charts used in the report
        items:
          $ref: '#/definitions/PartialReportChart'
  LogData:
    type: object
    required:
    - level
    - at
    - data
    properties:
      level:
        type: string
        enum:
        - INFO
        - WARN
        - ERROR
      at:
        type: string
        description: created timestamp
        example: '2017-01-24T13:57:52Z'
      message:
        type: string
      data:
        type: object
        additionalProperties:
          type: object
  HiringTeamAssignment:
    type: object
    required:
    - assign
    properties:
      assign:
        $ref: '#/definitions/ApiOperationCall'
      remove:
        $ref: '#/definitions/ApiOperationCall'
  AccrualConfig:
    type: object
    required:
    - frequency
    - accrualOffsetFromStartDate
    properties:
      frequency:
        type: string
        enum:
        - SEMI_MONTHLY
        - MONTHLY
        - WEEKLY
      monthlyDaysOfMonth:
        type: array
        items:
          type: integer
          format: int32
      weeklyStartDate:
        type: string
        format: date
      weeklyIncrement:
        type: integer
        format: int32
      balanceCapInWholeDays:
        type: integer
        format: int32
      accrualOffsetFromStartDate:
        type: integer
        format: int32
  Calendar:
    type: object
    required:
    - id
    - type
    - label
    - color
    - sensitive
    - status
    - isBuiltIn
    properties:
      id:
        type: string
        description: globally unique id
        example: 665f3aabe88164e4ef6c3a22
      orgId:
        type: string
        description: parent organization id
        example: 665f3ad1e47a82bf1d3d180b
      type:
        type: string
        description: type of calendar
        enum:
        - ANNIVERSARY
        - BIRTHDAY
        - COMP_REVIEW
        - REVIEW
        - SURVEY
        - TASK
        - TIMEOFF
        - START_DATE
        - END_DATE
        - CUSTOM
        - HOLIDAY
      label:
        type: string
        description: human-readable label for calendar
      description:
        type: string
      color:
        type: string
      imagePath:
        type: string
        pattern: ^[a-zA-Z0-9._/-]*$
      emoji:
        type: string
        description: emoji, if an emoji is used to represent the calendar
        example: 💥
        minItems: 0
        maxItems: 64
      sensitive:
        type: string
        description: base sensitivity of this calendar and entities in it -- should be PRIVATE, ORG or HIGH
        enum:
        - GLOBAL
        - ORG
        - SENSITIVE
        - PERSONAL
        - MANAGER
        - HIGH
        - PRIVATE
      shareAccess:
        type: array
        description: list of users and groups who have the content shared with them
        items:
          $ref: '#/definitions/ShareAccess'
      status:
        type: string
        description: whether the calendar is active or not
        enum:
        - ACTIVE
        - INACTIVE
      createId:
        type: string
        description: created by user id
        example: 588f7ee98f138b19220041a

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