Hex Projects API
The Projects API from Hex — 10 operation(s) for projects.
OpenAPI Specification
openapi: 3.0.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
nullable: true
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:
TimezoneDesignator:
type: string
description: An ISO 8601 timezone designator like +08:00.
StaticCellId:
type: string
format: uuid
description: Unique static ID for a cell. This can be found by going into the menu of a cell in the notebook.
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}$
ResponseRunId:
type: string
format: uuid
description: Unique ID for a run of a Hex 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}$
EnumValues_typeofSortDirectionEnum_:
type: string
enum:
- DESC
- ASC
EnumValues_typeofSortByEnum_:
type: string
enum:
- CREATED_AT
- LAST_EDITED_AT
- LAST_PUBLISHED_AT
NotificationRecipient:
properties:
id:
type: string
description: The Id of the recipient. For users and groups, these Ids are found in the settings panel in Hex, while the Id for Slack can be found within the Slack app or URL.
example: C0123456
name:
type: string
description: The human readable name for the user, group, or Slack channel.
example: data-team
isPrivate:
type: boolean
description: Whether or not the Slack channel is a private channel in the Slack workspace.
example: false
required:
- id
- name
type: object
additionalProperties: false
ProjectQueriedTablesApiResource:
properties:
values:
items:
$ref: '#/components/schemas/ProjectQueriedTableResource'
type: array
pagination:
$ref: '#/components/schemas/PaginationApiResource'
traceId:
type: string
required:
- values
- pagination
- traceId
type: object
additionalProperties: false
ShareProjectWithGroupError:
properties:
groupIds:
items:
$ref: '#/components/schemas/GroupId'
type: array
reason:
type: string
required:
- groupIds
- reason
type: object
additionalProperties: false
UserId:
type: string
format: uuid
description: Unique ID for a user. This can be found from the users page (in Settings).
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}$
EnumValues_typeofDayOfWeekApiEnum_:
type: string
enum:
- SUNDAY
- MONDAY
- TUESDAY
- WEDNESDAY
- THURSDAY
- FRIDAY
- SATURDAY
NotFoundParam:
type: string
description: Name of an input parameter passed to the API call that was not found in the project.
TraceId:
type: string
description: A unique identifier for this API request. The Hex Support team may request this value when debugging an issue.
DataConnectionId:
type: string
format: uuid
description: Unique ID for a data connection.
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}$
EnumValues_typeofScheduleCadenceApiEnum_:
type: string
enum:
- HOURLY
- DAILY
- WEEKLY
- MONTHLY
- CUSTOM
ScreenshotFormatType:
type: string
enum:
- png
- pdf
description: The file format of the generated screenshot.
RunStatusUrl:
type: string
description: URL to query the status of the project run via the Hex API
DayOfWeekApiEnum:
$ref: '#/components/schemas/EnumValues_typeofDayOfWeekApiEnum_'
ShareProjectWithWorkspaceError:
properties:
type:
type: string
enum:
- workspace
- publicWeb
reason:
type: string
required:
- type
- reason
type: object
additionalProperties: false
PaginationApiResource:
properties:
after:
allOf:
- $ref: '#/components/schemas/ApiPaginationCursor'
nullable: true
before:
allOf:
- $ref: '#/components/schemas/ApiPaginationCursor'
nullable: true
required:
- after
- before
type: object
additionalProperties: false
ProjectRunNotificationRecipient:
description: 'The recipient of a project run notification, which will include the type of recipient and additional configuration details.
This is used to determine who to send the notification to, and what triggers would qualify sending the notification.'
properties:
type:
$ref: '#/components/schemas/RunNotificationType'
subject:
type: string
body:
type: string
recipientType:
$ref: '#/components/schemas/NotificationRecipientType'
includeSuccessScreenshot:
type: boolean
description: If true, a screenshot of the project will be included in the notification when the project succeeds.
screenshotFormat:
items:
$ref: '#/components/schemas/ScreenshotFormatType'
type: array
description: 'The format of the screenshot to be included in the notification.
Defaults to png only if not specified and includeSuccessScreenshot is true.'
recipient:
$ref: '#/components/schemas/NotificationRecipient'
required:
- type
- recipientType
- includeSuccessScreenshot
- recipient
type: object
additionalProperties: false
NextPageUrl:
typ
# --- 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