Charthop app API

openapi: 3.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
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: app
paths:
  /v1/app:
    get:
      tags:
      - app
      summary: Return all publicly visible global apps
      operationId: findGlobalApps
      parameters:
      - name: tag
        in: query
        description: Tag to filter by
        required: false
        schema:
          type: string
      - name: from
        in: query
        description: App 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
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsApp'
        '400':
          description: bad request
        '404':
          description: not found
    post:
      tags:
      - app
      summary: Create a new app
      operationId: createApp
      responses:
        '201':
          description: app created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApp'
        description: App data to create
        required: true
  /v1/app/install/{appId}:
    get:
      tags:
      - app
      summary: Get all active installs of this app
      operationId: getActiveAppInstalls
      parameters:
      - name: appId
        in: path
        description: App id
        required: true
        schema:
          type: string
      - name: orgTypes
        in: query
        description: Comma-separated list of org types to include. Defaults to all org types.
        required: false
        schema:
          type: string
      - name: hasRunProcess
        in: query
        description: Whether to require that the app has run at least one process. Defaults to true.
        required: false
        schema:
          type: boolean
      - name: internalOptions
        in: query
        description: Filter app users by internal option key-value pair
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsUser'
  /v1/app/name/{appName}:
    get:
      tags:
      - app
      summary: Return a particular app by name
      operationId: getAppByName
      parameters:
      - name: appName
        in: path
        description: App name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      responses:
        '204':
          description: notification sent
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotifyRequest'
        required: true
  /v1/app/org/{orgId}:
    get:
      tags:
      - app
      summary: Return all active apps available for a particular org
      operationId: findApps
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: q
        in: query
        description: Search query
        required: false
        schema:
          type: string
      - name: type
        in: query
        description: Filter by type (app, bundle)
        required: false
        schema:
          type: string
      - name: tags
        in: query
        description: Filter by tags
        required: false
        schema:
          type: string
      - name: from
        in: query
        description: App 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
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsApp'
        '400':
          description: bad request
        '404':
          description: not found
  /v1/app/org/{orgId}/install:
    get:
      tags:
      - app
      summary: Find installed app users
      operationId: findInstalledApps
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: type
        in: query
        description: Filter by type (app, bundle)
        required: false
        schema:
          type: string
      - name: tags
        in: query
        description: Filter by tag
        required: false
        schema:
          type: string
      - name: statuses
        in: query
        description: 'Filter by App User statuses, comma-separated. Accepted values: [''NORMAL'', ''INACTIVE'', ''UNINSTALLED'']'
        required: false
        schema:
          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
        schema:
          type: boolean
      - name: from
        in: query
        description: App 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
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsUser'
        '400':
          description: bad request
        '404':
          description: not found
    post:
      tags:
      - app
      summary: Install an app for a particular org
      operationId: installApp
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '201':
          description: app installed
          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: App user data to create
        required: true
  /v1/app/org/{orgId}/install/name/{appName}:
    get:
      tags:
      - app
      summary: Get an installed app by name
      operationId: getInstalledAppByName
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appName
        in: path
        description: App name
        required: true
        schema:
          type: string
      - name: includeInactive
        in: query
        description: If the installed appUser is inactive, load inactive instead
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '201':
          description: app validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BundleInstallValidate'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
        description: App user data to create
        required: true
  /v1/app/org/{orgId}/install/{appUserId}:
    get:
      tags:
      - app
      summary: Get an installed app
      operationId: getInstalledApp
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          type: string
      - name: includeInactive
        in: query
        description: If the installed appUser is inactive, load inactive instead
        required: false
        schema:
          type: boolean
      responses:
        '204':
          description: app 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: App user data to update
        required: true
    delete:
      tags:
      - app
      summary: Uninstall an app
      operationId: uninstallApp
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          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
        schema:
          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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          type: string
      - name: operation
        in: path
        description: Operation id
        required: true
        schema:
          type: string
      - name: from
        in: query
        description: Pagination cursor (opaque 'next' from a prior result)
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of records to return
        required: false
        schema:
          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
        schema:
          type: string
          enum:
          - ORG
          - USER
      responses:
        '200':
          description: operation executed (inspect the result for the API's status/body)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalApiExecutionResult'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: object
  /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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          type: string
      - name: scope
        in: query
        description: Scopes
        required: false
        schema:
          type: string
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: revoked
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeMcpConnectionsRequest'
        required: true
  /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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisableSyncResponse'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisableSyncRequest'
        required: true
  /v1/app/org/{orgId}/install/{appUserId}/installdata/{installDataName}:
    get:
      tags:
      - app
      summary: Retrieve the current token for this app
      operationId: getAppInstallData
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          type: string
      - name: installDataName
        in: path
        description: Name
        required: true
        schema:
          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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OauthRefreshResponse'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: no active token / refresh failed — re-authorization required
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OauthRefreshRequest'
        required: true
  /v1/app/org/{orgId}/install/{appUserId}/run:
    post:
      tags:
      - app
      summary: Run an installed app
      operationId: runInstalledApp
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: app started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: object
  /v1/app/org/{orgId}/install/{appUserId}/token:
    get:
      tags:
      - app
      summary: Retrieve the current token for this app
      operationId: getAccessToken
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: appUserId
        in: path
        description: App user id
        required: true
        schema:
          type: string
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenResponse'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScopeRequest'
        required: true
  /v1/app/{appId}:
    get:
      tags:
      - app
      summary: Return a particular app by id
      operationId: getApp
      parameters:
      - name: appId
        in: path
        description: App id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        '400':
          description: bad request
        '404':
          description: not found
    patch:
      tags:
      - app
      summary: Update an existing app
      operationId: updateApp
      parameters:
      - name: appId
        in: path
        description: App id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: app 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/UpdateApp'
        description: App data to update
        required: true
    delete:
      tags:
      - app
      summary: Delete an app
      operationId: deleteApp
      parameters:
      - name: appId
        in: path
        description: App id
        required: true
        schema:
          type: string
      responses:
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
components:
  schemas:
    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'
    Geopoint:
      type: object
      required:
      - type
      - coordinates
      properties:
        type:
          type: string
          description: Type of point
          readOnly: true
        coordinates:
          type: array
          description: The longitude and latitude of the point
          readOnly: true
          items:
            type: number
            format: double
    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
    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
    Question:
      type: object
      required:
      - id
      - question
      - type
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent organization id (empty if global)
          example: 588f7ee98f138b19220041a7
        question:
          type: string
          description: text of the question
          example: What is your favorite color?
        questionTr:
          description: translations for the question text
          $ref: '#/components/schemas/Translations'
        fieldId:
          type: string
          description: if the question is linked to a field, the id of that field. Any question responses will be automatically saved to the field
          example: 588f7ee98f138b19220041a7
        type:
          type: string
          description: datatype of the question
          enum:
          - ADDRESS
          - AUDIO
          - BOOLEAN
          - COMP
          - COMPOUND
          - COMP_BAND
          - CONTACTS
          - CURRENCY
          - DATE
          - DECIMAL
          - ELAPSED_DAYS
          - ELAPSED_MONTHS
          - ELAPSED_YEARS
          - EMAIL
          - ENUM
          - ENUM_EXP

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