Skip to main content
API docs by Redocly

Hex API (1.0.0)

Download OpenAPI specification:Download

License: UNLICENSED

API specification for the Hex External API

CreatePresignedUrl

Create an embedded url for a project

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

Request Body schema: application/json
required
hexUserAttributes
object

A map of attributes meant to populate hex_user_attributes in the app for the running user. This must be a string to string map. For more complexity, you can do json serialization

scope
Array of strings

Optionally include additional permissions for a user to do in an embedded app. Valid scopes include:

EXPORT_PDF: allow users to download the app as a pdf EXPORT_CSV: allow users to download CSVs from tables

inputParameters
object

Optionall sets default values for input states. The keys are the names of the inputs and the values are the default values for those inputs.

expiresIn
number <double>
Default: "15000"

Optionally specify the expiration time of the embedding url in milliseconds. This represents the maximum allowed time between receiving the API response with the single-use signed URL, and requesting the signed URL for the iframe. Default is 15 seconds. Maximum value is 300 seconds (5 minutes).

object

Optionally customize the display of the embedded app

testMode
boolean

Run the embed API call in test mode. Does not run the app and will not count towards rate limits or embedding usage counts.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "hexUserAttributes": {
    },
  • "scope": [
    ],
  • "inputParameters": {
    },
  • "expiresIn": "15000",
  • "displayOptions": {
    },
  • "testMode": true,
  • "property1": null,
  • "property2": null
}

Response samples

Content type
application/json
{
  • "url": "string"
}

CreateProject

Create a new project.

Creates a new project in the workspace with the specified title. Optionally provide a description and project language.

Authorizations:
bearerAuth
Request Body schema: application/json
required
description
string
title
required
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "description": "string",
  • "type": "PROJECT",
  • "creator": {
    },
  • "owner": {
    },
  • "status": {
    },
  • "categories": [
    ],
  • "reviews": {
    },
  • "analytics": {
    },
  • "lastEditedAt": "string",
  • "lastPublishedAt": "string",
  • "createdAt": "string",
  • "archivedAt": "string",
  • "trashedAt": "string",
  • "schedules": [
    ],
  • "sharing": {
    }
}

ListProjects

List all viewable projects, sorted by most recently created first.

Authorizations:
bearerAuth
query Parameters
includeArchived
boolean
Default: false
includeComponents
boolean
Default: false
includeTrashed
boolean
Default: false
includeSharing
boolean
Default: false
statuses
Array of strings
Default: ""
categories
Array of strings
Default: ""
creatorEmail
string
Default: null
ownerEmail
string
Default: null
collectionId
string
Default: null
limit
integer <int32> (PageSize) [ 1 .. 100 ]
Default: "25"

Number of results to fetch per page for paginated requests

after
any
Default: null
before
any
Default: null
sortBy
string (SortByEnum)
Enum: "CREATED_AT" "LAST_EDITED_AT" "LAST_PUBLISHED_AT"
sortDirection
string (SortDirectionEnum)
Enum: "DESC" "ASC"

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "pagination": {
    }
}

GetQueriedTables

Given a project ID, return the list of warehouse tables queried in the project.

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

query Parameters
limit
integer <int32> (PageSize) [ 1 .. 100 ]
Default: "25"

Number of results to fetch per page for paginated requests

after
any
Default: null
before
any
Default: null

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "pagination": {
    },
  • "traceId": "string"
}

EditProjectSharingCollections

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.

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

Request Body schema: application/json
required
required
object
required
object
required
Array of objects <= 25 items
Array (<= 25 items)
access
required
string (AccessLevelEnum)
Enum: "NONE" "APP_ONLY" "CAN_VIEW" "CAN_EDIT" "FULL_ACCESS"
required
object

Responses

Request samples

Content type
application/json
{
  • "sharing": {
    }
}

Response samples

Content type
application/json
{
  • "project": {
    },
  • "errors": [
    ]
}

EditProjectSharingOrgAndPublic

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".

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

Request Body schema: application/json
required
required
object
publicWeb
string (PublicWebAccessLevel)
Enum: "NONE" "APP_ONLY" "CAN_VIEW" "CAN_EDIT" "FULL_ACCESS"
workspace
string (AccessLevelEnum)
Enum: "NONE" "APP_ONLY" "CAN_VIEW" "CAN_EDIT" "FULL_ACCESS"

Responses

Request samples

Content type
application/json
{
  • "sharing": {
    }
}

Response samples

Content type
application/json
{
  • "project": {
    },
  • "errors": [
    ]
}

EditProjectSharingGroups

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".

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

Request Body schema: application/json
required
required
object
required
object
required
Array of objects <= 25 items
Array (<= 25 items)
access
required
string (AccessLevelEnum)
Enum: "NONE" "APP_ONLY" "CAN_VIEW" "CAN_EDIT" "FULL_ACCESS"
required
object

Responses

Request samples

Content type
application/json
{
  • "sharing": {
    }
}

Response samples

Content type
application/json
{
  • "project": {
    },
  • "errors": [
    ]
}

EditProjectSharingUsers

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".

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

Request Body schema: application/json
required
required
object
required
object
required
Array of objects <= 25 items
Array (<= 25 items)
access
required
string (AccessLevelEnum)
Enum: "NONE" "APP_ONLY" "CAN_VIEW" "CAN_EDIT" "FULL_ACCESS"
required
object

Responses

Request samples

Content type
application/json
{
  • "sharing": {
    }
}

Response samples

Content type
application/json
{
  • "project": {
    },
  • "errors": [
    ]
}

UpdateProject

Use this endpoint to add or remove a status (including endorsements) from a project

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

Request Body schema: application/json
required
status
string or null

Responses

Request samples

Content type
application/json
{
  • "status": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "title": "string",
  • "description": "string",
  • "type": "PROJECT",
  • "creator": {
    },
  • "owner": {
    },
  • "status": {
    },
  • "categories": [
    ],
  • "reviews": {
    },
  • "analytics": {
    },
  • "lastEditedAt": "string",
  • "lastPublishedAt": "string",
  • "createdAt": "string",
  • "archivedAt": "string",
  • "trashedAt": "string",
  • "schedules": [
    ],
  • "sharing": {
    }
}

GetProject

Get metadata about a single project.

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
path Parameters
projectId
required
string

The project to fetch.

query Parameters
includeSharing
boolean
Default: false

Whether to include sharing metadata in the response.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "description": "string",
  • "type": "PROJECT",
  • "creator": {
    },
  • "owner": {
    },
  • "status": {
    },
  • "categories": [
    ],
  • "reviews": {
    },
  • "analytics": {
    },
  • "lastEditedAt": "string",
  • "lastPublishedAt": "string",
  • "createdAt": "string",
  • "archivedAt": "string",
  • "trashedAt": "string",
  • "schedules": [
    ],
  • "sharing": {
    }
}

IngestSemanticProject

Ingest a semantic project from a zip file.

This API endpoint is subject to a maximum of 3 requests per minute.

Authorizations:
bearerAuth
path Parameters
semanticProjectId
required
string <uuid> (SemanticProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a Hex semantic project. This can be found from the semantic projects admin panel (in Settings).

Request Body schema: application/json
required
verbose
boolean
Default: true

Whether to respond with detail on which components of the semantic layer were successfully synced

debug
boolean
Default: false

Whether to include additional debug information

dryRun
boolean

If enabled, the sync will not actually write to the database

Responses

Request samples

Content type
application/json
{
  • "verbose": true,
  • "debug": false,
  • "dryRun": true
}

Response samples

Content type
application/json
{
  • "traceId": "string",
  • "contents": [
    ],
  • "warnings": [
    ],
  • "skipped": {
    },
  • "problems": [
    ],
  • "debug": {
    }
}

UpdateSemanticProject

Use this endpoint to add or remove a status (including endorsements) from datasets and views within a semantic project

This endpoint uses atomic semantics - if any update in the batch fails validation, the entire request fails and no changes are applied.

Authorizations:
bearerAuth
path Parameters
semanticProjectId
required
string <uuid> (SemanticProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a Hex semantic project. This can be found from the semantic projects admin panel (in Settings).

Request Body schema: application/json
required
required
Array of objects (SemanticObjectUpdate)

Array of updates to apply

Array
type
required
string
Enum: "DATASET" "VIEW"

The type of object to update

name
required
string

The name of the dataset or view

status
required
string or null

The status name to apply, or null to remove the current status

Responses

Request samples

Content type
application/json
{
  • "updates": [
    ]
}

Response samples

Content type
application/json
{
  • "updated": {
    }
}

RunProject

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.

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

header Parameters
flag-config-override
string
Request Body schema: application/json
optional
inputParams
object

Optionally specify input parameters for this project run. These should be structured as a dictionary of key/value pairs, where the key name matches the name of the variable in the Hex project.

Only parameters that are added to the published app can be set via this request parameter. Any additional inputs will be ignored. It is invalid to pass in both a viewId and inputParams.

If no input parameters are provided, the project will be run with the default input values. Note that if input parameters are provided, this run will not be able to update the cached values for the project, and the updateCache setting (below) will be ignored.

dryRun
boolean
Default: "false"

When true, this endpoint will perform a dry run that does not run the project. This can be useful for validating the structure of an API call, and inspecting a dummy response, without running a project.

updateCache
boolean
Deprecated
Array of objects (ProjectRunNotification)

Optionally specify a list of notification details that will be delivered once a project run completes. Notifications can be configured for delivery to Slack channels, Hex users, or Hex groups.

updatePublishedResults
boolean
Default: "false"

When true, the cached state of the published app will be updated with the latest run results. You must have at least "Can Edit" permissions on the project to do so. Note: this cannot be set to true if custom input parameters are provided.

useCachedSqlResults
boolean
Default: "true"

When false, the project will run without using any cached SQL results, and will update those cached SQL results.

viewId
string

Optionally specify a SavedView viewId to use for the project run. If specified, the saved view's inputs will be used for the project run. It is invalid to pass in both a viewId and inputParams. If not specified, the default inputs will be used.

Responses

Request samples

Content type
application/json
{
  • "inputParams": {
    },
  • "dryRun": "false",
  • "updateCache": true,
  • "notifications": [
    ],
  • "updatePublishedResults": "false",
  • "useCachedSqlResults": "true",
  • "viewId": "string"
}

Response samples

Content type
application/json
{
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  • "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  • "runUrl": "string",
  • "runStatusUrl": "string",
  • "traceId": "string",
  • "projectVersion": 0,
  • "notifications": [
    ]
}

GetProjectRuns

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.

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

query Parameters
limit
integer <int32> (PageSize) [ 1 .. 100 ]
Default: "25"

Number of results to fetch per page for paginated requests

offset
integer <int32> (Offset) >= 0
Default: "0"

Offset for paginated requests

statusFilter
string (ProjectRunStatus)
Enum: "PENDING" "RUNNING" "ERRORED" "COMPLETED" "KILLED" "UNABLE_TO_ALLOCATE_KERNEL"

Current status of a project run

runTriggerFilter
string (RunTypeFilter)
Enum: "API" "SCHEDULED" "APP_REFRESH" "ALL"

Filter by how the run was triggered Valid values: API, SCHEDULED, APP_REFRESH

Responses

Response samples

Content type
application/json
{
  • "runs": [
    ],
  • "nextPage": "string",
  • "previousPage": "string",
  • "traceId": "string"
}

GetRunStatus

Get the status of a project run.

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

runId
required
string <uuid> (InputRunId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

header Parameters
enable-expanded-stats
string

Responses

Response samples

Content type
application/json
{
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  • "projectVersion": 0,
  • "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  • "runUrl": "string",
  • "status": "PENDING",
  • "runTrigger": "API",
  • "startTime": "2019-08-24T14:15:22Z",
  • "endTime": "2019-08-24T14:15:22Z",
  • "elapsedTime": 0.1,
  • "flagConfigOverride": "string",
  • "traceId": "string",
  • "notifications": [
    ],
  • "stateEvents": [
    ]
}

CancelRun

Cancel a project run.

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

runId
required
string <uuid> (InputRunId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

Responses

Response samples

Content type
application/json
{
  • "details": "string",
  • "traceId": "string",
  • "reason": "string"
}

GetChartImageFromRun

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.

The optional width and height query params set the output image size in pixels. Both must be provided to apply, and must be between 100 and 2000. The optional includeTitle query param includes the chart title in the image when true.

Rate limit: 20 requests per minute.

Authorizations:
bearerAuth
path Parameters
projectId
required
string <uuid> (ProjectId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

runId
required
string <uuid> (InputRunId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

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.

staticId
required
string <uuid> (StaticCellId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique static ID for a cell. This can be found by going into the menu of a cell in the notebook.

query Parameters
width
integer <int32> (ChartImageDimension) [ 100 .. 2000 ]

Chart image total dimension (width or height) in pixels.

height
integer <int32> (ChartImageDimension) [ 100 .. 2000 ]

Chart image total dimension (width or height) in pixels.

includeTitle
boolean

Responses

Response samples

Content type
application/json
{
  • "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  • "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  • "staticId": "a1fad2c1-0d45-4ff9-a7df-774e2bcf0e0b",
  • "imageBase64": "string",
  • "mimeType": "string"
}

GetGroup

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid> (GroupId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a group. This can be found from the groups page (in Settings).

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "createdAt": "string"
}

DeleteGroup

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid> (GroupId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a group. This can be found from the groups page (in Settings).

Responses

Response samples

Content type
application/json
{
  • "details": "string",
  • "traceId": "string",
  • "reason": "string"
}

EditGroup

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid> (GroupId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a group. This can be found from the groups page (in Settings).

Request Body schema: application/json
required
object
name
string (Name) non-empty

Responses

Request samples

Content type
application/json
{
  • "members": {
    },
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "createdAt": "string"
}

ListGroups

Authorizations:
bearerAuth
query Parameters
after
any
Default: null
before
any
Default: null
limit
integer <int32> (LargerPageSize) [ 1 .. 500 ]
Default: "25"

Number of results to fetch per page for paginated requests

sortBy
string (ListGroupsSortByEnum)
Enum: "CREATED_AT" "NAME"
sortDirection
string (SortDirectionEnum)
Enum: "DESC" "ASC"

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "pagination": {
    }
}

CreateGroup

Authorizations:
bearerAuth
Request Body schema: application/json
required
object (GroupMembers)
name
required
string (Name) non-empty

Responses

Request samples

Content type
application/json
{
  • "members": {
    },
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "members": {
    }
}

GetDataConnection

Authorizations:
bearerAuth
path Parameters
dataConnectionId
required
string <uuid> (DataConnectionId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a data connection.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "type": "athena",
  • "description": "string",
  • "connectionDetails": {
    },
  • "connectViaSsh": true,
  • "includeMagic": true,
  • "allowWritebackCells": true,
  • "schemaFilters": {
    },
  • "schemaRefreshSchedule": {
    },
  • "schemaRefreshAccess": "ADMINS",
  • "sharing": {
    }
}

EditDataConnection

Authorizations:
bearerAuth
path Parameters
dataConnectionId
required
string <uuid> (DataConnectionId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a data connection.

Request Body schema: application/json
required
object
schemaRefreshAccess
string (DataConnectionSchemaRefreshAccess)
Enum: "ADMINS" "USERS_WITH_QUERY_ACCESS"
object or null
object
allowWritebackCells
boolean
includeMagic
boolean
connectViaSsh
boolean
description
string
object or object or object or object or object or object or object (EditConnectionDetails)
name
string

Responses

Request samples

Content type
application/json
{
  • "sharing": {
    },
  • "schemaRefreshAccess": "ADMINS",
  • "schemaRefreshSchedule": {
    },
  • "schemaFilters": {
    },
  • "allowWritebackCells": true,
  • "includeMagic": true,
  • "connectViaSsh": true,
  • "description": "string",
  • "connectionDetails": {
    },
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "type": "athena",
  • "description": "string",
  • "connectionDetails": {
    },
  • "connectViaSsh": true,
  • "includeMagic": true,
  • "allowWritebackCells": true,
  • "schemaFilters": {
    },
  • "schemaRefreshSchedule": {
    },
  • "schemaRefreshAccess": "ADMINS",
  • "sharing": {
    }
}

ListDataConnections

Authorizations:
bearerAuth
query Parameters
after
any
Default: null
before
any
Default: null
limit
integer <int32> (PageSize) [ 1 .. 100 ]
Default: "25"

Number of results to fetch per page for paginated requests

sortBy
string (ListDataConnectionsSortByEnum)
Enum: "CREATED_AT" "NAME"
sortDirection
string (SortDirectionEnum)
Enum: "DESC" "ASC"

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "pagination": {
    }
}

CreateDataConnection

Authorizations:
bearerAuth
Request Body schema: application/json
required
object
schemaRefreshAccess
string (DataConnectionSchemaRefreshAccess)
Enum: "ADMINS" "USERS_WITH_QUERY_ACCESS"
object (SchemaRefreshScheduleApiResource)
object
allowWritebackCells
boolean
includeMagic
boolean
connectViaSsh
boolean
description
string
required
object or object or object or object or object or object or object (CreateConnectionDetails)
type
required
string (DataConnectionApiType)
Enum: "athena" "bigquery" "clickhouse" "databricks" "postgres" "redshift" "snowflake" "trino"
name
required
string (Name) non-empty

Responses

Request samples

Content type
application/json
{
  • "sharing": {
    },
  • "schemaRefreshAccess": "ADMINS",
  • "schemaRefreshSchedule": {
    },
  • "schemaFilters": {
    },
  • "allowWritebackCells": true,
  • "includeMagic": true,
  • "connectViaSsh": true,
  • "description": "string",
  • "connectionDetails": {
    },
  • "type": "athena",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "type": "athena",
  • "description": "string",
  • "connectionDetails": {
    },
  • "connectViaSsh": true,
  • "includeMagic": true,
  • "allowWritebackCells": true,
  • "schemaFilters": {
    },
  • "schemaRefreshSchedule": {
    },
  • "schemaRefreshAccess": "ADMINS",
  • "sharing": {
    }
}

UpdateDataConnectionSchema

Use this endpoint to add or remove a status (including endorsements) from databases, schemas, and tables within a data connection

This endpoint uses atomic semantics - if any update in the batch fails validation, the entire request fails and no changes are applied

Authorizations:
bearerAuth
path Parameters
dataConnectionId
required
string <uuid> (DataConnectionId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a data connection.

Request Body schema: application/json
required
required
Array of objects (SchemaObjectUpdate)

Array of updates to apply

Array
type
required
string
Enum: "DATABASE" "SCHEMA" "TABLE"

The type of object to update

name
required
string

The name of the object - simple for DATABASE, qualified for SCHEMA/TABLE

status
required
string or null

The status name to apply, or null to remove the current status

Responses

Request samples

Content type
application/json
{
  • "updates": [
    ]
}

Response samples

Content type
application/json
{
  • "updated": {
    }
}

GetCollection

Authorizations:
bearerAuth
path Parameters
collectionId
required
string <uuid> (CollectionId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a collection.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "creator": {
    },
  • "sharing": {
    }
}

EditCollection

Authorizations:
bearerAuth
path Parameters
collectionId
required
string <uuid> (CollectionId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a collection.

Request Body schema: application/json
required
object
description
string
name
string (Name) non-empty

Responses

Request samples

Content type
application/json
{
  • "sharing": {
    },
  • "description": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "creator": {
    },
  • "sharing": {
    }
}

ListCollections

Authorizations:
bearerAuth
query Parameters
after
any
Default: null
before
any
Default: null
limit
integer <int32> (PageSize) [ 1 .. 100 ]
Default: "25"

Number of results to fetch per page for paginated requests

sortBy
string (ListCollectionsSortByEnum)
Value: "NAME"

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "pagination": {
    }
}

CreateCollection

Authorizations:
bearerAuth
Request Body schema: application/json
required
object (CollectionApiResourceSharing)
description
string
name
required
string

Responses

Request samples

Content type
application/json
{
  • "sharing": {
    },
  • "description": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "creator": {
    },
  • "sharing": {
    }
}

UpsertGuideDraft

Update or create guide drafts by filePath.

Accepts a dictionary mapping file paths to their contents. For each file:

  • If the guide doesn't exist, it will be created.
  • If the guide exists but has no draft, a new draft will be created.
  • If the guide exists with a draft, the draft contents will be updated.
Authorizations:
bearerAuth
Request Body schema: application/json
required
forceWrite
boolean

If true, will overwrite an existing guide that is synced from a different source if there is a guide of the same name e.g. guide1.md is authored in Hex, request.files includes guide1.md -> this will overwrite the guide that was authored in Hex

default: false

required
Array of objects

A mapping from filePath -> contents

Responses

Request samples

Content type
application/json
{
  • "forceWrite": true,
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "files": [
    ],
  • "warnings": [
    ],
  • "traceId": "string"
}

PublishGuideDrafts

Publish all currently drafted guides.

Authorizations:
bearerAuth
Request Body schema: application/json
required
orgGuideFileIds
Array of strings <uuid> (OrgGuideFileId) [ items <uuid >^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}... ]

The IDs of the guides to publish if publishAllGuides is false.

publishAllDraftGuides
boolean

Publish all draft guides (ignores the orgGuideFileIds field if true)

Responses

Request samples

Content type
application/json
{
  • "orgGuideFileIds": [
    ],
  • "publishAllDraftGuides": true
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "publishedGuides": [
    ],
  • "traceId": "string"
}

DeleteGuideDraft

Authorizations:
bearerAuth
path Parameters
orgGuideFileId
required
string <uuid> (OrgGuideFileId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a guide file. This can be found by going into the menu of a guide file in the guide files side bar.

Responses

Response samples

Content type
application/json
{
  • "details": "string",
  • "traceId": "string",
  • "reason": "string"
}

GetChartImageFromLogic

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.

The optional width and height query params set the output image size in pixels. Both must be provided to apply, and must be between 100 and 2000. The optional includeTitle query param includes the chart title in the image when true.

Rate limit: 20 requests per minute.

Authorizations:
bearerAuth
path Parameters
cellId
required
string <uuid> (CellId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...

Unique ID for a cell. This can be found by going into the menu of a cell in the notebook.

query Parameters
width
integer <int32> (ChartImageDimension) [ 100 .. 2000 ]

Chart image total dimension (width or height) in pixels.

height
integer <int32> (ChartImageDimension) [ 100 .. 2000 ]

Chart image total dimension (width or height) in pixels.

includeTitle
boolean

Responses

Response samples

Content type
application/json
{
  • "cellId": "e0f2424e-962c-4579-836d-e31fbb8fbece",
  • "imageBase64": "string",
  • "mimeType": "string"
}

GetCell

Get a single cell by ID

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
path Parameters
cellId
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "staticId": "string",
  • "cellType": "CODE",
  • "label": "string",
  • "dataConnectionId": "string",
  • "contents": {
    },
  • "projectId": "string"
}

UpdateCell

Update a cell's source and/or data connection. For SQL cells, can update the SQL source, output dataframe, and data connection. For code and markdown cells, can update the source. Returns the updated cell.

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
path Parameters
cellId
required
string
Request Body schema: application/json
required
dataConnectionId
string or null

Data connection to attach to a SQL cell. Pass null to detach the existing data connection.

object

Responses

Request samples

Content type
application/json
{
  • "dataConnectionId": "string",
  • "contents": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "staticId": "string",
  • "cellType": "CODE",
  • "label": "string",
  • "dataConnectionId": "string",
  • "contents": {
    },
  • "projectId": "string"
}

DeleteCell

Delete a cell from the draft version of a project by ID

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
path Parameters
cellId
required
string

Responses

Response samples

Content type
application/json
{
  • "cellId": "string"
}

CreateCell

Create a new cell in the draft version of a project

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
Request Body schema: application/json
required
projectId
required
string

The project to create the cell in.

cellType
required
string
Enum: "CODE" "SQL" "MARKDOWN"

The type of cell to create. Determines which contents variant is required.

label
string

Optional label for the cell.

required
object or object or object

Cell contents. Provide exactly the variant matching cellType: codeCell for CODE, sqlCell for SQL, markdownCell for MARKDOWN.

object

Controls where the new cell is placed. If omitted, the cell is appended to the end of the project.

Responses

Request samples

Content type
application/json
{
  • "projectId": "string",
  • "cellType": "CODE",
  • "label": "string",
  • "contents": {
    },
  • "location": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "staticId": "string",
  • "cellType": "CODE",
  • "label": "string",
  • "dataConnectionId": "string",
  • "contents": {
    },
  • "projectId": "string"
}

ListCells

List cells from the draft version of a project. Returns code, SQL, and markdown cell contents.

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
query Parameters
projectId
required
string

The project to list cells from

after
string or null
Default: null
before
string or null
Default: null
limit
number [ 1 .. 100 ]
Default: 25

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "pagination": {
    }
}

ExportProject

Exports a Hex project in the *.hex.yaml format.

Availability of this endpoint varies by organization. Contact Hex support to request access.

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
Request Body schema: application/json
required
projectId
required
string

The project to export.

integer or string or string
Default: "draft"

Used to specify the version to export. "draft" is the current notebook version; "latest" is the latest published app version.

Responses

Request samples

Content type
application/json
{
  • "projectId": "string",
  • "version": "draft"
}

Response samples

Content type
application/json
{
  • "filename": "string",
  • "content": "string"
}

CreateThread

Start an agent thread with a prompt. The Hex agent will analyze data and respond to the prompt. The thread runs asynchronously — poll its status or visit the returned URL to view progress.

Availability of this endpoint varies by organization. Contact Hex support to request access.

This endpoint is subject to the following rate limits:

  • hex-send-thread-message: Rate limits for sending messages to threads
    • Dynamic per minute maximum based on Hex traffic
    • Dynamic per hour maximum based on Hex traffic
Authorizations:
bearerAuth
Request Body schema: application/json
required
prompt
required
string non-empty
object

Entities referenced by the prompt

previewId
string or null
projectId
string or null

Run the thread against an existing project. Mutually exclusive with newProject

newProject
boolean or null

Create a new project for the thread to work on. Mutually exclusive with projectId

muted
boolean or null

If true, the thread will not be shown in any aggregated UI surfaces and will not contribute to user-facing statistics. The thread is still individually viewable. Only applies for non-project-backed threads (ignored when projectId or newProject is set). This is distinct from a sensitive thread.

Responses

Request samples

Content type
application/json
{
  • "prompt": "string",
  • "attachments": {
    },
  • "previewId": "string",
  • "projectId": "string",
  • "newProject": true,
  • "muted": true
}

Response samples

Content type
application/json
{
  • "threadId": "string",
  • "url": "string",
  • "createdAt": "string",
  • "projectId": "string"
}

ListThreads

List agent threads in the workspace, sorted by most recently created first. Requires Manager org role or higher. Workspace admins receive every non-private thread; managers receive threads they created plus Threads-type threads on projects they have access to. Threads marked private are returned with their title redacted.

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
query Parameters
after
string or null
Default: null
before
string or null
Default: null
limit
number [ 1 .. 100 ]
Default: 25
source
string or null
Enum: "HEX" "SLACK" "MCP" "PUBLIC_API" null
userId
string or null
type
string or null
Enum: "THREADS" "NOTEBOOK" "MODELING" null
numDays
integer or null > 0
hasFeedback
boolean or null
roles
string or null

Comma-separated list of user org roles to filter by (ADMIN, MANAGER, EDITOR, EXPLORER, MEMBER, GUEST)

warnings
string or null

Comma-separated list of warning types to filter by (DATA_LIMITATION, USER_DOUBT, MISSING_CONTEXT, OTHER)

topicIds
string or null

Comma-separated list of topic IDs to filter by

Responses

Response samples

Content type
application/json
{
  • "threads": [
    ],
  • "pagination": {
    }
}

GetThread

Get the response of an agent thread. Returns the current status (RUNNING, IDLE, or ERROR) and the agent's response content when available.

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "creditsUsed": 0,
  • "topics": [
    ],
  • "warnings": [
    ],
  • "feedback": [
    ],
  • "warningsGeneratedAt": "string",
  • "threadSummary": "string",
  • "threadIntent": "string",
  • "model": "string",
  • "userId": "string",
  • "type": "string",
  • "source": "string",
  • "createdAt": "string",
  • "sensitive": true,
  • "threadId": "string",
  • "status": "IDLE",
  • "url": "string",
  • "error": {
    },
  • "response": [
    ]
}

GetThreadMessages

List the messages in an agent thread, rendered as a single flat list of text blocks. Within a page messages are chronological (oldest first); each text block is prefixed with the authoring role, and thinking and error blocks are tagged. Tool-call, tool-result, and mention blocks are omitted, and inline references are left as raw tags. By default the most recent page is returned (matching the MCP get_thread tool); pass the before cursor to fetch older messages and after to fetch newer ones. Supports cursor pagination with a maximum page size of 50.

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
path Parameters
threadId
required
string
query Parameters
after
string or null
Default: null
before
string or null
Default: null
limit
number [ 1 .. 50 ]
Default: 25

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "pagination": {
    }
}

ContinueThread

Continue an existing agent thread with a follow-up prompt. This endpoint does not support queuing: the thread must be idle before a follow-up can be sent.

Availability of this endpoint varies by organization. Contact Hex support to request access.

This endpoint is subject to the following rate limits:

  • hex-send-thread-message: Rate limits for sending messages to threads
    • Dynamic per minute maximum based on Hex traffic
    • Dynamic per hour maximum based on Hex traffic
Authorizations:
bearerAuth
path Parameters
id
required
string
Request Body schema: application/json
required
prompt
required
string non-empty
object

Entities referenced by the prompt

Responses

Request samples

Content type
application/json
{
  • "prompt": "string",
  • "attachments": {
    }
}

Response samples

Content type
application/json
{
  • "threadId": "string",
  • "url": "string"
}

Me

Returns information about the current logged in user. User metadata will be omitted when authenticating with a workspace token.

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "org": {
    },
  • "token": {
    }
}

ListUsers

List all users in the workspace

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
query Parameters
after
string or null
Default: null
before
string or null
Default: null
limit
number [ 1 .. 500 ]
Default: 25
sortBy
string
Default: "NAME"
Enum: "NAME" "EMAIL"
sortDirection
string
Default: "ASC"
Enum: "ASC" "DESC"
groupId
string or null
userIds
string or null

Comma-separated list of user IDs

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "pagination": {
    }
}

DeactivateUser

Deactivate a user

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
path Parameters
userId
required
string

Responses

Response samples

Content type
application/json
{
  • "user": {
    }
}

ListTopics

List thread topics in the workspace, sorted by name.

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
query Parameters
after
string or null
Default: null
before
string or null
Default: null
limit
number [ 1 .. 100 ]
Default: 25

Responses

Response samples

Content type
application/json
{
  • "topics": [
    ],
  • "pagination": {
    }
}

ListDraftGuides

List draft guides

This endpoint is subject to the following rate limits:

  • hex-api: Default rate limit group for the Hex API
    • Max 30 requests per minute
Authorizations:
bearerAuth
query Parameters
limit
number [ 1 .. 100 ]
Default: 100
after
string or null
Default: null
before
string or null
Default: null
externalSource
string or null

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "pagination": {
    }
}