Hex Projects API

openapi: 3.0.3
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}/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}:
    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
                  nullable: true
              type: object
      tags:
      - Projects
    get:
      operationId: GetProject
      summary: GetProject
      description: "Get metadata about a single project.\n\nThis endpoint is subject to the following rate limits:\n- `hex-api`: Default rate limit group for the Hex API\n  - Max requests per minute may vary (default: 30)\n  - Max requests per hour may vary (default: 1800)"
      parameters:
      - in: path
        name: projectId
        description: The project to fetch.
        schema:
          type: string
          description: The project to fetch.
        required: true
      - in: query
        name: includeSharing
        description: Whether to include sharing metadata in the response.
        schema:
          type: boolean
          default: false
          description: Whether to include sharing metadata in the response.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  title:
                    type: string
                  description:
                    type: string
                    nullable: true
                  type:
                    type: string
                    enum:
                    - PROJECT
                    - COMPONENT
                  creator:
                    type: object
                    properties:
                      email:
                        type: string
                    required:
                    - email
                  owner:
                    type: object
                    properties:
                      email:
                        type: string
                    required:
                    - email
                  status:
                    type: object
                    nullable: true
                    properties:
                      name:
                        type: string
                    required:
                    - name
                  categories:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        description:
                          type: string
                          nullable: true
                      required:
                      - name
                      - description
                  reviews:
                    type: object
                    properties:
                      required:
                        type: boolean
                    required:
                    - required
                  analytics:
                    type: object
                    properties:
                      appViews:
                        type: object
                        properties:
                          allTime:
                            type: integer
                          lastSevenDays:
                            type: integer
                          lastFourteenDays:
                            type: integer
                          lastThirtyDays:
                            type: integer
                        required:
                        - allTime
                        - lastSevenDays
                        - lastFourteenDays
                        - lastThirtyDays
                      lastViewedAt:
                        type: string
                        nullable: true
                      publishedResultsUpdatedAt:
                        type: string
                        nullable: true
                    required:
                    - appViews
                    - lastViewedAt
                    - publishedResultsUpdatedAt
                  lastEditedAt:
                    type: string
                  lastPublishedAt:
                    type: string
                    nullable: true
                  createdAt:
                    type: string
                  archivedAt:
                    type: string
                    nullable: true
                  trashedAt:
                    type: string
                    nullable: true
                  schedules:
                    type: array
                    items:
                      type: object
                      properties:
                        cadence:
                          type: string
                          enum:
                          - HOURLY
                          - DAILY
                          - WEEKLY
                          - MONTHLY
                          - CUSTOM
                        enabled:
                          type: boolean
                        hourly:
                          type: object
                          nullable: true
                          properties:
                            minute:
                              type: integer
                            timezone:
                              type: string
                          required:
                          - minute
                          - timezone
                        daily:
                          type: object
                          nullable: true
                          properties:
                            hour:
                              type: integer
                            minute:
                              type: integer
                            timezone:
                              type: string
                          required:
                          - hour
                          - minute
                          - timezone
                        weekly:
                          type: object
                          nullable: true
                          properties:
                            dayOfWeek:
                              type: string
                              enum:
                              - SUNDAY
                              - MONDAY
                              - TUESDAY
                              - WEDNESDAY
                              - THURSDAY
                              - FRIDAY
                              - SATURDAY
                            hour:
                              type: integer
                            minute:
                              type: integer
                            timezone:
                              type: string
                          required:
                          - dayOfWeek
                          - hour
                          - minute
                          - timezone
                        monthly:
                          type: object
                          nullable: true
                          properties:
                            day:
                              type: integer
                            hour:
                              type: integer
                            minute:
                              type: integer
                            timezone:
                              type: string
                          required:
                          - day
                          - hour
                          - minute
                          - timezone
                        custom:
                          type: object
                          nullable: true
                          properties:
                            cron:
                              type: string
                            timezone:
                              type: string
                          required:
                          - cron
                          - timezone
                      required:
                      - cadence
                      - enabled
                      - hourly
                      - daily
                      - weekly
                      - monthly
                      - custom
                  sharing:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          type: object
                          properties:
                            user:
                              type: object
                              properties:
                                email:
                                  type: string
                              required:
                              - email
                            access:
                              type: string
                              enum:
                              - NONE
                              - APP_ONLY
                              - CAN_VIEW
                              - CAN_EDIT
                              - FULL_ACCESS
                          required:
                          - user
                          - access
                      collections:
                        type: array
                        items:
                          type: object
                          properties:
                            collection:
                              type: object
                              properties:
                                name:
                                  type: string
                              required:
                              - name
                            access:
                              type: string
                              enum:
                              - NONE
                              - APP_ONLY
                              - CAN_VIEW
                              - CAN_EDIT
                              - FULL_ACCESS
                          required:
                          - collection
                          - access
                      groups:
                        type: array
                        items:
                          type: object
                          properties:
                            group:
                              type: object
                              properties:
                                name:
                                  type: string
                              required:
                              - name
                            access:
                              type: string
                              enum:
                              - NONE
                              - APP_ONLY
                              - CAN_VIEW
                              - CAN_EDIT
                              - FULL_ACCESS
                          required:
                          - group
                          - access
                      workspace:
                        type: object
                        properties:
                          access:
                            type: string
                            enum:
                            - NONE
                            - APP_ONLY
                            - CAN_VIEW
                            - CAN_EDIT
                            - FULL_ACCESS
                        required:
                        - access
                      publicWeb:
                        type: object
                        properties:
                          access:
                            type: string
                            enum:
                            - NONE
                            - APP_ONLY
                            - CAN_VIEW
                            - CAN_EDIT
                            - FULL_ACCESS
                        required:
                        - access
                      support:
                        type: object
                        properties:
                          access:
                            type: string
                            enum:
                            - NONE
                            - APP_ONLY
                            - CAN_VIEW
                            - CAN_EDIT
                            - FULL_ACCESS
                        required:
                        - access
                    required:
                    - users
                    - collections
                    - groups
                    - workspace
                    - publicWeb
                    - support
                required:
                - id
                - title
                - description
                - type
                - creator
                - owner
                - status
                - categories
                - reviews
                - analytics
                - lastEditedAt
                - lastPublishedAt
                - createdAt
                - archivedAt
                - trashedAt
                - schedules
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.BAD_REQUEST'
        '401':
          description: Authorization not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.UNAUTHORIZED'
        '403':
          description: Insufficient access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.FORBIDDEN'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.NOT_FOUND'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
      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:
      

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