OpenAPI Specification
openapi: 3.0.0
info:
title: Hex Cells 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: Cells
paths:
/v1/cells:
get:
operationId: ListCells
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CellsListApiResource'
'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: 'List all cells
Returns cells from the draft version of the project only, not the published app.
Requires a project id for filtering.
For SQL and CODE cells, includes the source code content.'
parameters:
- in: query
name: projectId
required: true
schema:
$ref: '#/components/schemas/ProjectId'
- 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
tags:
- Cells
post:
operationId: CreateCell
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CellApiResource'
'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: 'Create a new cell
Creates a new cell in the draft version of a project.
Currently only CODE and SQL cell types are supported.
Requires EDIT_PROJECT_CONTENTS permission on the project.'
parameters: []
requestBody:
required: true
content:
application/json:
schema:
properties:
location:
properties:
childPosition:
type: string
enum:
- FIRST
- LAST
description: Where to place the cell within the parent section. Defaults to LAST.
parentCellId:
$ref: '#/components/schemas/CellId'
description: Insert the new cell as a child of a section (parent) cell. Use with childPosition to control placement within the section.
insertAfterCellId:
$ref: '#/components/schemas/CellId'
description: Insert the new cell after this cell ID. The cell must belong to the target project.
type: object
description: Controls where the new cell is placed. If omitted, the cell is appended to the end of the project.
contents:
properties:
markdownCell:
properties:
source:
type: string
required:
- source
type: object
sqlCell:
properties:
outputDataframe:
type: string
isDataframeSql:
type: boolean
description: 'Set to true to create a dataframe SQL cell that queries the outputs of other
SQL cells in the project instead of a data connection.
Mutually exclusive with dataConnectionId.'
dataConnectionId:
$ref: '#/components/schemas/DataConnectionId'
source:
type: string
required:
- source
type: object
codeCell:
properties:
source:
type: string
required:
- source
type: object
type: object
label:
type: string
cellType:
type: string
enum:
- CODE
- SQL
- MARKDOWN
projectId:
$ref: '#/components/schemas/ProjectId'
required:
- contents
- cellType
- projectId
type: object
tags:
- Cells
/v1/cells/{cellId}:
get:
operationId: GetCell
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CellApiResource'
'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: 'Get a single cell by ID
Returns cells from the draft version of the project only, not the published app.
Returns the cell details including id, staticId, cellType, label, dataConnectionId,
source contents (for CODE and SQL cells), and projectId.'
parameters:
- in: path
name: cellId
required: true
schema:
$ref: '#/components/schemas/CellId'
tags:
- Cells
patch:
operationId: UpdateCell
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CellApiResource'
'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 a cell''s source and/or data connection
Updates the source code and/or data connection ID for a cell.
For SQL cells, can update SQL source and data connection ID.
For code cells, can update code source.
Requires EDIT_PROJECT_CONTENTS permission on the project containing the cell.'
parameters:
- in: path
name: cellId
required: true
schema:
$ref: '#/components/schemas/CellId'
requestBody:
required: true
content:
application/json:
schema:
properties:
contents:
properties:
markdownCell:
properties:
source:
type: string
required:
- source
type: object
sqlCell:
properties:
outputDataframe:
type: string
source:
type: string
required:
- source
type: object
codeCell:
properties:
source:
type: string
required:
- source
type: object
type: object
dataConnectionId:
allOf:
- $ref: '#/components/schemas/DataConnectionId'
nullable: true
type: object
tags:
- Cells
delete:
operationId: DeleteCell
responses:
'204':
description: ''
'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: 'Delete a cell
Permanently deletes a cell from the draft version of a project.
Requires EDIT_PROJECT_CONTENTS permission on the project containing the cell.'
parameters:
- in: path
name: cellId
required: true
schema:
$ref: '#/components/schemas/CellId'
tags:
- Cells
/v1/cells/{cellId}/image:
get:
operationId: GetChartImageFromLogic
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ChartImageResponsePayload'
'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 the current notebook session by cellId.
The "cellId" path parameter should be the cell''s ID (scoped to a
specific version), as opposed to its staticId (which remains stable across versions).
Returns a JSON object containing the base64-encoded PNG image of the chart cell
as it currently appears in the Logic view, along with the cell ID 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: cellId
required: true
schema:
$ref: '#/components/schemas/CellId'
tags:
- Cells
components:
schemas:
TraceId:
type: string
description: A unique identifier for this API request. The Hex Support team may request this value when debugging an issue.
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}$
TsoaErrorResponsePayload:
properties:
details:
type: string
traceId:
$ref: '#/components/schemas/TraceId'
reason:
type: string
required:
- reason
type: object
CellId:
type: string
format: uuid
description: Unique 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}$
ApiPaginationCursor:
type: string
description: 'A cursor string used with `before` and `after` parameters to paginate through a list
of items on the API.'
CellType:
$ref: '#/components/schemas/EnumValues_typeofCellType_'
ChartImageResponsePayload:
properties:
cellId:
$ref: '#/components/schemas/CellId'
imageBase64:
type: string
mimeType:
type: string
required:
- cellId
- imageBase64
- mimeType
type: object
additionalProperties: false
EnumValues_typeofCellType_:
type: string
enum:
- CODE
- MARKDOWN
- DISPLAY_TABLE
- INPUT
- SQL
- VEGA_CHART
- CELL_GROUP
- METRIC
- TEXT
- MAP
- WRITEBACK
- DBT_METRIC
- PIVOT
- FILTER
- COMPONENT_IMPORT
- CHART
- BLOCK
- EXPLORE
- COLLAPSIBLE
CellApiResource:
properties:
id:
$ref: '#/components/schemas/CellId'
staticId:
$ref: '#/components/schemas/StaticCellId'
cellType:
$ref: '#/components/schemas/CellType'
label:
type: string
nullable: true
dataConnectionId:
allOf:
- $ref: '#/components/schemas/DataConnectionId'
nullable: true
contents:
properties:
markdownCell:
properties:
source:
type: string
required:
- source
type: object
nullable: true
sqlCell:
properties:
outputDataframe:
type: string
source:
type: string
required:
- outputDataframe
- source
type: object
nullable: true
codeCell:
properties:
source:
type: string
required:
- source
type: object
nullable: true
required:
- markdownCell
- sqlCell
- codeCell
type: object
projectId:
$ref: '#/components/schemas/ProjectId'
required:
- id
- staticId
- cellType
- label
- dataConnectionId
- contents
- projectId
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
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}$
PageSize:
type: integer
format: int32
default: '25'
description: Number of results to fetch per page for paginated requests
minimum: 1
maximum: 100
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}$
CellsListApiResource:
properties:
values:
items:
$ref: '#/components/schemas/CellApiResource'
type: array
pagination:
$ref: '#/components/schemas/PaginationApiResource'
required:
- values
- pagination
type: object
additionalProperties: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer