Hex Projects API

openapi: 3.2.0
info:
  title: Hex Cells Projects API
  version: 1.0.0
  description: API specification for the Hex External API
  license:
    name: UNLICENSED
  contact: {}
servers:
- url: https://app.hex.tech/api
security:
- bearerAuth: []
tags:
- name: Projects
paths:
  /v1/projects:
    post:
      operationId: CreateProject
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectApiResource'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: 'Create a new project.


        Creates a new project in the workspace with the specified title.

        Optionally provide a description and project language.'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                description:
                  type: string
                title:
                  type: string
              required:
              - title
              type: object
      tags:
      - Projects
    get:
      operationId: ListProjects
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsListApiResource'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: List all viewable projects, sorted by most recently created first.
      parameters:
      - in: query
        name: includeArchived
        required: false
        schema:
          default: false
          type: boolean
      - in: query
        name: includeComponents
        required: false
        schema:
          default: false
          type: boolean
      - in: query
        name: includeTrashed
        required: false
        schema:
          default: false
          type: boolean
      - in: query
        name: includeSharing
        required: false
        schema:
          default: false
          type: boolean
      - in: query
        name: statuses
        required: false
        schema:
          default: []
          type: array
          items:
            type: string
      - in: query
        name: categories
        required: false
        schema:
          default: []
          type: array
          items:
            type: string
      - in: query
        name: creatorEmail
        required: false
        schema:
          default: null
          type: string
      - in: query
        name: ownerEmail
        required: false
        schema:
          default: null
          type: string
      - in: query
        name: collectionId
        required: false
        schema:
          default: null
          type: string
      - in: query
        name: limit
        required: false
        schema:
          $ref: '#/components/schemas/PageSize'
      - in: query
        name: after
        required: false
        schema:
          default: null
      - in: query
        name: before
        required: false
        schema:
          default: null
      - in: query
        name: sortBy
        required: false
        schema:
          $ref: '#/components/schemas/SortByEnum'
      - in: query
        name: sortDirection
        required: false
        schema:
          $ref: '#/components/schemas/SortDirectionEnum'
      tags:
      - Projects
  /v1/projects/{projectId}:
    get:
      operationId: GetProject
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectApiResource'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: Get metadata about a single project.
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      - in: query
        name: includeSharing
        required: false
        schema:
          default: false
          type: boolean
      tags:
      - Projects
    patch:
      operationId: UpdateProject
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectApiResource'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: Use this endpoint to add or remove a status (including endorsements) from a project
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                status:
                  type:
                  - string
                  - 'null'
              type: object
      tags:
      - Projects
  /v1/projects/{projectId}/queriedTables:
    get:
      operationId: GetQueriedTables
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectQueriedTablesApiResource'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: Given a project ID, return the list of warehouse tables queried in the project.
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          $ref: '#/components/schemas/PageSize'
      - in: query
        name: after
        required: false
        schema:
          default: null
      - in: query
        name: before
        required: false
        schema:
          default: null
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      tags:
      - Projects
  /v1/projects/{projectId}/sharing/collections:
    patch:
      operationId: EditProjectSharingCollections
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditProjectSharingCollectionsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: 'Add a project to collections or remove it from collections.

        For projects, use `CAN_VIEW` to grant the UI permission labeled "Can explore".

        Use `APP_ONLY` to grant the UI permission labeled "Can view app".

        Workspace tokens calling this endpoint need to have "Collections -> Write access" scope

        in addition to "Projects -> Write access" scope.'
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                sharing:
                  properties:
                    upsert:
                      properties:
                        collections:
                          items:
                            properties:
                              access:
                                $ref: '#/components/schemas/AccessLevelEnum'
                              collection:
                                properties:
                                  id:
                                    $ref: '#/components/schemas/CollectionId'
                                required:
                                - id
                                type: object
                            required:
                            - access
                            - collection
                            type: object
                          type: array
                          maxItems: 25
                      required:
                      - collections
                      type: object
                  required:
                  - upsert
                  type: object
              required:
              - sharing
              type: object
      tags:
      - Projects
  /v1/projects/{projectId}/sharing/workspaceAndPublic:
    patch:
      operationId: EditProjectSharingOrgAndPublic
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditProjectSharingWorkspaceAndPublicResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: 'Update workspace or public-web sharing for a project.

        For projects, use `CAN_VIEW` to grant the UI permission labeled "Can explore".

        Use `APP_ONLY` to grant the UI permission labeled "Can view app".'
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                sharing:
                  properties:
                    publicWeb:
                      $ref: '#/components/schemas/PublicWebAccessLevel'
                    workspace:
                      $ref: '#/components/schemas/AccessLevelEnum'
                  type: object
              required:
              - sharing
              type: object
      tags:
      - Projects
  /v1/projects/{projectId}/sharing/groups:
    patch:
      operationId: EditProjectSharingGroups
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditProjectSharingGroupsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: 'Add groups to a project or update/remove their project sharing access.

        For projects, use `CAN_VIEW` to grant the UI permission labeled "Can explore".

        Use `APP_ONLY` to grant the UI permission labeled "Can view app".'
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                sharing:
                  properties:
                    upsert:
                      properties:
                        groups:
                          items:
                            properties:
                              access:
                                $ref: '#/components/schemas/AccessLevelEnum'
                              group:
                                properties:
                                  id:
                                    $ref: '#/components/schemas/GroupId'
                                required:
                                - id
                                type: object
                            required:
                            - access
                            - group
                            type: object
                          type: array
                          maxItems: 25
                      required:
                      - groups
                      type: object
                  required:
                  - upsert
                  type: object
              required:
              - sharing
              type: object
      tags:
      - Projects
  /v1/projects/{projectId}/sharing/users:
    patch:
      operationId: EditProjectSharingUsers
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EditProjectSharingUsersResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: 'Add users to a project or update/remove their project sharing access.

        For projects, use `CAN_VIEW` to grant the UI permission labeled "Can explore".

        Use `APP_ONLY` to grant the UI permission labeled "Can view app".'
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                sharing:
                  properties:
                    upsert:
                      properties:
                        users:
                          items:
                            properties:
                              access:
                                $ref: '#/components/schemas/AccessLevelEnum'
                              user:
                                properties:
                                  id:
                                    $ref: '#/components/schemas/UserId'
                                required:
                                - id
                                type: object
                            required:
                            - access
                            - user
                            type: object
                          type: array
                          maxItems: 25
                      required:
                      - users
                      type: object
                  required:
                  - upsert
                  type: object
              required:
              - sharing
              type: object
      tags:
      - Projects
  /v1/projects/{projectId}/runs:
    post:
      operationId: RunProject
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectRunResponsePayload'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '422':
          description: ''
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/TsoaErrorResponsePayload'
                - $ref: '#/components/schemas/InvalidParamPayload'
        '503':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: 'Trigger a run of the latest published version of a project.


        This API endpoint is subject to a maximum of 20 requests per minute and 60 requests per hour.'
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      - in: header
        name: flag-config-override
        required: false
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunProjectRequestBody'
      tags:
      - Projects
    get:
      operationId: GetProjectRuns
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectRunsResponsePayload'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: 'Get the status of runs of a project.

        By default, all run types are returned (API-triggered, scheduled, and publish/refresh runs).

        Use the `runTriggerFilter` parameter to filter to a specific type.'
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      - in: query
        name: limit
        required: false
        schema:
          $ref: '#/components/schemas/PageSize'
      - in: query
        name: offset
        required: false
        schema:
          $ref: '#/components/schemas/Offset'
      - in: query
        name: statusFilter
        required: false
        schema:
          $ref: '#/components/schemas/ProjectRunStatus'
      - description: 'Filter by how the run was triggered

          Valid values: `API`, `SCHEDULED`, `APP_REFRESH`'
        in: query
        name: runTriggerFilter
        required: false
        schema:
          $ref: '#/components/schemas/RunTypeFilter'
      tags:
      - Projects
  /v1/projects/{projectId}/runs/{runId}:
    get:
      operationId: GetRunStatus
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectStatusResponsePayload'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: Get the status of a project run.
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      - in: path
        name: runId
        required: true
        schema:
          $ref: '#/components/schemas/InputRunId'
      - in: header
        name: enable-expanded-stats
        required: false
        schema:
          type: string
      tags:
      - Projects
    delete:
      operationId: CancelRun
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: Cancel a project run.
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      - in: path
        name: runId
        required: true
        schema:
          $ref: '#/components/schemas/InputRunId'
      tags:
      - Projects
  /v1/projects/{projectId}/runs/{runId}/cells/{staticId}/image:
    get:
      operationId: GetChartImageFromRun
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChartImageFromRunResponsePayload'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: 'Get the rendered PNG image of a chart cell from a completed run by staticCellId.

        The "staticId" path parameter should be the cell''s staticId (which remains stable across project versions),

        as opposed to its cellId (which is scoped to a specific version).


        Returns a JSON object containing the base64-encoded PNG image of the chart cell

        as rendered at the time of the specified run, along with project/run/cell IDs and MIME type.

        The cell must have been executed and must not be in an error state.

        Only chart-type cells are supported.


        Rate limit: 20 requests per minute.'
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          $ref: '#/components/schemas/ProjectId'
      - in: path
        name: runId
        required: true
        schema:
          $ref: '#/components/schemas/InputRunId'
      - in: path
        name: staticId
        required: true
        schema:
          $ref: '#/components/schemas/StaticCellId'
      tags:
      - Projects
components:
  schemas:
    ProjectId:
      type: string
      format: uuid
      description: Unique ID for a Hex project. This can be found in the Variables side bar of the Logic View of a project, or by visiting the Project, and copying the UUID after `hex` in the URL.
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    ProjectStatusResponsePayload:
      description: Response format returned by the getRunStatus endpoint
      properties:
        projectId:
          $ref: '#/components/schemas/ProjectId'
        projectVersion:
          $ref: '#/components/schemas/ProjectVersion'
        runId:
          $ref: '#/components/schemas/ResponseRunId'
        runUrl:
          $ref: '#/components/schemas/RunUrl'
        status:
          $ref: '#/components/schemas/ProjectRunStatus'
        runTrigger:
          $ref: '#/components/schemas/ProjectStatusRunTrigger'
          description: 'How the run was triggered: `API`, `SCHEDULED`, or `APP_REFRESH`'
        startTime:
          type:
          - string
          - 'null'
          format: date-time
          description: UTC timestamp of when the project run started
        endTime:
          type:
          - string
          - 'null'
          format: date-time
          description: UTC timestamp of when the project run finished
        elapsedTime:
          type:
          - number
          - 'null'
          format: double
          description: Total elapsed time for the project run in milliseconds
        flagConfigOverride:
          type: string
        traceId:
          $ref: '#/components/schemas/TraceId'
        notifications:
          items:
            $ref: '#/components/schemas/ProjectRunNotificationRecipient'
          type: array
        stateEvents:
          items:
            $ref: '#/components/schemas/StateEvent'
          type: array
      required:
      - projectId
      - projectVersion
      - runId
      - runUrl
      - status
      - runTrigger
      - startTime
      - endTime
      - elapsedTime
      - traceId
      type: object
      additionalProperties: false
    EditProjectSharingCollectionsResponse:
      properties:
        project:
          $ref: '#/components/schemas/ProjectApiResource'
        errors:
          items:
            $ref: '#/components/schemas/ShareProjectWithCollectionError'
          type: array
      required:
      - project
      type: object
      additionalProperties: false
    InputRunId:
      type: string
      format: uuid
      description: Unique ID for a run of a Hex project. This ID is part of the response returned by the RunProject endpoint. The GetProjectRuns endpoint can also be used to find the specific runs for a project.
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    ShareProjectWithWorkspaceError:
      properties:
        type:
          type: string
          enum:
          - workspace
          - publicWeb
        reason:
          type: string
      required:
      - type
      - reason
      type: object
      additionalProperties: false
    EditProjectSharingUsersResponse:
      properties:
        project:
          $ref: '#/components/schemas/ProjectApiResource'
        errors:
          items:
            $ref: '#/components/schemas/ShareProjectWithUserError'
          type: array
      required:
      - project
      type: object
      additionalProperties: false
    ProjectRunNotification:
      description: The configuration details for notifications, which are sent after a run has completed.
      properties:
        type:
          $ref: '#/components/schemas/RunNotificationType'
        includeSuccessScreenshot:
          type: boolean
          description: If true, a screenshot of the project will be included in the notification when the project succeeds.
        screenshotFormat:
          $ref: '#/components/schemas/ScreenshotFormatType'
          description: 'The format of the screenshot to be included in the notification.

            Defaults to png if not specified and includeSuccessScreenshot is true.'
        slackChannelIds:
          items:
            type: string
          type: array
          description: 'The Slack channels to send the notification to.

            The Hex Slackbot must be added to any private channels included.

            The Slack Channel Id can be found in the channel''s settings from within the Slack app.'
        userIds:
          items:
            type: string
          type: array
          description: The Hex user Ids to send the notification to. These Ids can be found and copied from the Setting's User panel in Hex.
        groupIds:
          items:
            type: string
          type: array
          description: The Hex group Ids to send the notification to. These Ids can be found and copied from the Setting's Group panel in Hex.
        subject:
          type: string
          description: An optional message to use as the subject of the notification.
        body:
          type: string
          description: An optional message to include in the body of the notification.
      required:
      - type
      - includeSuccessScreenshot
      type: object
      additionalProperties: false
    ProjectsListApiResource:
      properties:
        values:
          items:
            $ref: '#/components/schemas/ProjectApiResource'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationApiResource'
      required:
      - values
      - pagination
      type: object
      additionalProperties: false
    PublicWebAccessLev

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