Hex API (1.0.0)
Download OpenAPI specification:Download
API specification for the Hex External API
IngestSemanticModel
Authorizations:
path Parameters
semanticModelId required | string <uuid> (SemanticModelId) ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}... Unique ID for a Hex semantic model. This can be found from the semantic models admin panel (in Settings). |
Request Body schema: application/jsonrequired
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
- Payload
{- "verbose": true,
- "debug": false,
- "dryRun": true
}
Response samples
- 201
- 400
- 403
- 415
- 502
{- "traceId": "string",
- "warnings": [
- "string"
], - "skipped": {
- "property1": null,
- "property2": null
}, - "debug": {
- "metricflowModelSchemas": { }
}
}
GetProject
Get metadata about a single project.
Authorizations:
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 |
query Parameters
includeSharing | boolean Default: false |
Responses
Response samples
- 200
- 403
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "title": "string",
- "description": "string",
- "type": "PROJECT",
- "creator": {
- "email": "string"
}, - "owner": {
- "email": "string"
}, - "status": {
- "name": "string"
}, - "categories": [
- {
- "description": "string",
- "name": "string"
}
], - "reviews": {
- "required": true
}, - "analytics": {
- "publishedResultsUpdatedAt": "string",
- "lastViewedAt": "string",
- "appViews": {
- "lastThirtyDays": 0,
- "lastFourteenDays": 0,
- "lastSevenDays": 0,
- "allTime": 0
}
}, - "lastEditedAt": "string",
- "lastPublishedAt": "string",
- "createdAt": "string",
- "archivedAt": "string",
- "trashedAt": "string",
- "schedules": [
- {
- "cadence": "HOURLY",
- "enabled": true,
- "hourly": {
- "timezone": "string",
- "minute": 59
}, - "daily": {
- "timezone": "string",
- "minute": 59,
- "hour": 23
}, - "weekly": {
- "timezone": "string",
- "minute": 59,
- "hour": 23,
- "dayOfWeek": "SUNDAY"
}, - "monthly": {
- "timezone": "string",
- "minute": 59,
- "hour": 23,
- "day": 1
}, - "custom": {
- "timezone": "string",
- "cron": "string"
}
}
], - "sharing": {
- "users": [
- {
- "access": "NONE",
- "user": {
- "email": "string"
}
}
], - "collections": [
- {
- "access": "NONE",
- "collection": {
- "name": "string"
}
}
], - "groups": [
- {
- "access": "NONE",
- "group": {
- "name": "string"
}
}
], - "workspace": {
- "access": "NONE"
}, - "publicWeb": {
- "access": "NONE"
}, - "support": {
- "access": "NONE"
}
}
}
ListProjects
List all viewable projects, sorted by most recently created first.
Authorizations:
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 |
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
- 200
- 400
- 403
{- "values": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "title": "string",
- "description": "string",
- "type": "PROJECT",
- "creator": {
- "email": "string"
}, - "owner": {
- "email": "string"
}, - "status": {
- "name": "string"
}, - "categories": [
- {
- "description": "string",
- "name": "string"
}
], - "reviews": {
- "required": true
}, - "analytics": {
- "publishedResultsUpdatedAt": "string",
- "lastViewedAt": "string",
- "appViews": {
- "lastThirtyDays": 0,
- "lastFourteenDays": 0,
- "lastSevenDays": 0,
- "allTime": 0
}
}, - "lastEditedAt": "string",
- "lastPublishedAt": "string",
- "createdAt": "string",
- "archivedAt": "string",
- "trashedAt": "string",
- "schedules": [
- {
- "cadence": "HOURLY",
- "enabled": true,
- "hourly": {
- "timezone": "string",
- "minute": 59
}, - "daily": {
- "timezone": "string",
- "minute": 59,
- "hour": 23
}, - "weekly": {
- "timezone": "string",
- "minute": 59,
- "hour": 23,
- "dayOfWeek": "SUNDAY"
}, - "monthly": {
- "timezone": "string",
- "minute": 59,
- "hour": 23,
- "day": 1
}, - "custom": {
- "timezone": "string",
- "cron": "string"
}
}
], - "sharing": {
- "users": [
- {
- "access": "NONE",
- "user": {
- "email": "string"
}
}
], - "collections": [
- {
- "access": "NONE",
- "collection": {
- "name": "string"
}
}
], - "groups": [
- {
- "access": "NONE",
- "group": {
- "name": "string"
}
}
], - "workspace": {
- "access": "NONE"
}, - "publicWeb": {
- "access": "NONE"
}, - "support": {
- "access": "NONE"
}
}
}
], - "pagination": {
- "after": "string",
- "before": "string"
}
}
RunProject
Trigger a run of the latest published version of a project.
Authorizations:
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 |
Request Body schema: application/jsonoptional
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
- Payload
{- "inputParams": {
- "text_input_1": "Hello World",
- "numeric_input_1": 123
}, - "dryRun": "false",
- "updateCache": true,
- "notifications": [
- {
- "type": "ALL",
- "includeSuccessScreenshot": "true",
- "slackChannelIds": [
- "C0000000"
], - "userIds": [
- "uuid-user-1",
- "uuid-user-2"
]
}, - {
- "type": "FAILURE",
- "includeSuccessScreenshot": "false",
- "userIds": [
- "uuid-user-1"
], - "groupIds": [
- "uuid-group-1"
]
}
], - "updatePublishedResults": "false",
- "useCachedSqlResults": "true",
- "viewId": "string"
}
Response samples
- 201
- 400
- 403
- 422
- 503
{- "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
- "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
- "runUrl": "string",
- "runStatusUrl": "string",
- "traceId": "string",
- "projectVersion": 0,
- "notifications": [
- {
- "type": "SUCCESS",
- "subject": "string",
- "body": "string",
- "recipientType": "USER",
- "includeSuccessScreenshot": true,
- "screenshotFormat": [
- "png"
], - "recipient": {
- "id": "C0123456",
- "name": "data-team",
- "isPrivate": false
}
}
]
}
GetProjectRuns
Get the status of the API-triggered runs of a project.
Authorizations:
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 |
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 |
Responses
Response samples
- 200
- 400
- 403
- 422
{- "runs": [
- {
- "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
- "projectVersion": 0,
- "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
- "runUrl": "string",
- "status": "PENDING",
- "startTime": "2019-08-24T14:15:22Z",
- "endTime": "2019-08-24T14:15:22Z",
- "elapsedTime": 0.1,
- "traceId": "string",
- "notifications": [
- {
- "type": "SUCCESS",
- "subject": "string",
- "body": "string",
- "recipientType": "USER",
- "includeSuccessScreenshot": true,
- "screenshotFormat": [
- "png"
], - "recipient": {
- "id": "C0123456",
- "name": "data-team",
- "isPrivate": false
}
}
]
}
], - "nextPage": "string",
- "previousPage": "string",
- "traceId": "string"
}
GetRunStatus
Get the status of a project run.
Authorizations:
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 |
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
- 200
- 400
- 403
- 422
{- "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
- "projectVersion": 0,
- "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
- "runUrl": "string",
- "status": "PENDING",
- "startTime": "2019-08-24T14:15:22Z",
- "endTime": "2019-08-24T14:15:22Z",
- "elapsedTime": 0.1,
- "traceId": "string",
- "notifications": [
- {
- "type": "SUCCESS",
- "subject": "string",
- "body": "string",
- "recipientType": "USER",
- "includeSuccessScreenshot": true,
- "screenshotFormat": [
- "png"
], - "recipient": {
- "id": "C0123456",
- "name": "data-team",
- "isPrivate": false
}
}
]
}
CancelRun
Cancel a project run.
Authorizations:
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 |
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
- 400
- 403
- 422
{- "details": "string",
- "traceId": "string",
- "reason": "string"
}
CreatePresignedUrl
Create an embedded url for a project
Authorizations:
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 |
Request Body schema: application/jsonrequired
hexUserAttributes required | 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 | |
property name* additional property | any |
Responses
Request samples
- Payload
{- "hexUserAttributes": {
- "orgId": "my-org-id",
- "groupId": "my-group-id"
}, - "scope": [
- "string"
], - "inputParameters": {
- "property1": null,
- "property2": null
}, - "expiresIn": "15000",
- "displayOptions": {
- "theme": "light",
- "noEmbedOutline": true,
- "noEmbedFooter": true
}, - "property1": null,
- "property2": null
}
Response samples
- 200
- 400
- 403
- 422
{- "url": "string"
}