--- title: Hex API Integration on Truto slug: hex category: Business Intelligence canonical: "https://truto.one/integrations/detail/hex/" --- # Hex API Integration on Truto **Category:** Business Intelligence **Status:** Generally available ## MCP-ready AI tools Truto exposes 58 tools for Hex that AI agents can call directly. - **create_a_hex_embedding_create_presigned_url** — Create a presigned URL for embedding a Hex project app. Returns: url. Required: project_id. Optional body fields let you pass user attributes, input defaults, extra scopes, expiry, and display options. - **list_all_hex_projects** — List all viewable Hex projects, sorted by most recently created first. Returns: id, title, description, type, creator, owner, status, categories, reviews, analytics, lastEditedAt, lastPublishedAt, createdAt, archivedAt, trashedAt, schedules, sharing. Max 100 per page. - **create_a_hex_project** — Create a new Hex project in the workspace with a title and optional description. Returns the created project including id, title, description, owner, status, and createdAt. Required: title. - **get_single_hex_project_by_id** — Get metadata about a single Hex project by id. Returns: id, title, description, type, creator, owner, status, categories, reviews, analytics, lastEditedAt, lastPublishedAt, createdAt, archivedAt, trashedAt, schedules, sharing. Required: id. - **update_a_hex_project_by_id** — Add or remove a status, including endorsements, from a Hex project by id; pass null as the status to remove the current one. Returns the updated project with id, title, status, and createdAt. Required: id. - **list_all_hex_project_queried_tables** — List the warehouse tables queried in a Hex project. Returns each queried table's dataConnectionId, dataConnectionName, and tableName. Max 100 per page. Required: project_id. - **hex_sharing_collections_bulk_update** — Add a Hex project to collections or remove it from collections. Returns the updated project including id, title, status, sharing, and createdAt. Max 25 collections per request; CAN_VIEW grants 'Can explore' and APP_ONLY grants 'Can view app' access. Required: project_id, sharing. - **get_single_hex_project_run_by_id** — Get the status of a Hex project run by id. Returns: projectId, projectVersion, runId, runUrl, status, runTrigger, startTime, endTime, elapsedTime, flagConfigOverride, traceId, notifications, stateEvents. Required: id, project_id. - **delete_a_hex_project_run_by_id** — Cancel a Hex project run by id. Returns an empty 204 response on success. Required: id, project_id. - **list_all_hex_project_runs** — List the status of a Hex project's runs, including API-triggered, scheduled, and publish/refresh runs. Returns run records with projectId, runId, runUrl, status, runTrigger, startTime, and elapsedTime. Required: project_id. - **create_a_hex_project_run** — Trigger a run of the latest published version of a Hex project. Returns: projectId, runId, runUrl, runStatusUrl, traceId, projectVersion, notifications. Required: project_id. - **get_single_hex_group_by_id** — Get a Hex group by id. Returns: id, name, createdAt. Required: id. - **update_a_hex_group_by_id** — Edit a Hex group by id to rename it or add and remove members. Returns: id, name, createdAt. Required: id. - **delete_a_hex_group_by_id** — Delete a Hex group by id. Returns an empty 204 response on success. Required: id. - **list_all_hex_groups** — List Hex groups. Returns: id, name, createdAt. - **create_a_hex_group** — Create a Hex group with a name and optional initial members. Returns: id, name, members. Required: name. - **list_all_hex_data_connections** — List the Hex workspace's data connections. Returns: id, name, type, description, sensitivity, connectionDetails, connectViaSsh, includeMagic, allowWritebackCells, schemaFilters, schemaRefreshSchedule, schemaRefreshAccess, sharing. Supports sorting by NAME or CREATED_AT; max 100 per page. - **create_a_hex_data_connection** — Create a new data connection in Hex. Returns: id, name, type, description, sensitivity, connectionDetails, connectViaSsh, includeMagic, allowWritebackCells, schemaFilters, schemaRefreshSchedule, schemaRefreshAccess, sharing. Required: name, type, connectionDetails. - **get_single_hex_data_connection_by_id** — Get a single Hex data connection by id. Returns: id, name, type, description, sensitivity, connectionDetails, connectViaSsh, includeMagic, allowWritebackCells, schemaFilters, schemaRefreshSchedule, schemaRefreshAccess, sharing. Required: id. - **update_a_hex_data_connection_by_id** — Update an existing Hex data connection by id. Returns: id, name, type, description, sensitivity, connectionDetails, connectViaSsh, includeMagic, allowWritebackCells, schemaFilters, schemaRefreshSchedule, schemaRefreshAccess, sharing. Required: id. - **hex_data_connection_schemas_bulk_update** — Add or remove statuses (including endorsements) on databases, schemas, and tables in a Hex data connection. Returns: updated. Atomic: if any update in the batch fails validation, the entire request fails and no changes are applied. Required: data_connection_id, updates. - **delete_a_hex_guides_draft_by_id** — Delete a guide's draft in Hex by id. Returns an empty 204 response on success. Required: id. - **hex_guides_drafts_bulk_update** — Update or create Hex guide drafts by file path — existing drafts are updated, and missing guides or drafts are created. Returns: files, warnings, traceId. Required: files. - **create_a_hex_guides_publish** — Publish all currently drafted guides in Hex. Returns: message, publishedGuides, traceId. - **get_single_hex_collection_by_id** — Get a single Hex collection by id. Returns: id, name, description, creator, sharing. Required: id. - **update_a_hex_collection_by_id** — Edit a Hex collection by id. Returns: id, name, description, creator, sharing. Required: id. - **list_all_hex_collections** — List Hex collections. Returns: id, name, description, creator, sharing. - **create_a_hex_collection** — Create a new Hex collection. Returns: id, name, description, creator, sharing. Required: name. - **get_single_hex_cell_by_id** — Get a single Hex cell by id. Returns: id, staticId, cellType, label, dataConnectionId, contents, projectId. Required: id. - **update_a_hex_cell_by_id** — Update a Hex cell's source and/or data connection by id; SQL cells can also update the output dataframe. contents must be wrapped by the cell type: {"codeCell": {"source": "..."}}, {"sqlCell": {"source": "..."}} or {"markdownCell": {"source": "..."}}. Returns the updated cell: id, staticId, cellType, label, contents, projectId. Required: id. - **delete_a_hex_cell_by_id** — Delete a cell from the draft version of a Hex project by id. Returns: cellId. Required: id. - **list_all_hex_cells** — List cells from the draft version of a Hex project, including code, SQL, and markdown contents. Returns: id, staticId, cellType, label, dataConnectionId, contents, projectId. Required: projectId. - **create_a_hex_cell** — Create a new cell in the draft version of a Hex project. contents must be an object wrapped by the cell type that matches cellType: {"codeCell": {"source": "..."}} for CODE, {"sqlCell": {"source": "...", "dataConnectionId": "..."}} for SQL, or {"markdownCell": {"source": "..."}} for MARKDOWN. Returns the created cell: id, staticId, cellType, label, contents, projectId. Required: projectId, cellType, contents. - **get_single_hex_cell_output_by_id** — Get the latest output preview for a SQL cell in Hex's active draft notebook session. Returns: projectId, runId, cell, result. This endpoint is unstable — Hex may make breaking changes without notice. Required: id. - **get_single_hex_cell_image_by_id** — Get the rendered PNG image of a chart cell in Hex from the project's current draft notebook session. Returns: cellId, imageBase64, mimeType. Only executed, non-error chart-type cells are supported. Required: id. - **hex_cell_images_search** — Get the rendered PNG image of a chart cell from a specific run of a Hex project. Returns: projectId, runId, staticId, imageBase64, mimeType. Required: project_id, run_id, cell_id. - **create_a_hex_compute_profile_batch** — Update the compute profile (kernel image and/or kernel size) on up to 250 Hex projects in one batch request. Returns: projects. A single permission failure rejects the whole batch; cross-org project IDs are silently dropped. Required: projectIds. - **hex_sharing_groups_bulk_update** — Update group sharing access on a Hex project: add groups, change their access level (NONE, APP_ONLY, CAN_VIEW, CAN_EDIT, FULL_ACCESS), or remove access with NONE. Returns the updated project: id, title, status, sharing. Up to 25 groups per call. Required: project_id, sharing. - **hex_sharing_users_bulk_update** — Update Hex project sharing for users — add users, change their access (CAN_VIEW, APP_ONLY, CAN_EDIT, FULL_ACCESS) or remove it with NONE. Returns the updated project with id, title, status, and sharing. Max 25 users per request. Required: project_id, sharing. - **hex_sharing_workspace_and_publics_bulk_update** — Update workspace or public-web sharing for a Hex project. Returns the updated project including id, title, status, and sharing. Omitted workspace/publicWeb values are left unchanged. Required: project_id, sharing. - **create_a_hex_projects_export** — Export a Hex project in the *.hex.yaml format. Returns the exported file's filename and its YAML-encoded project content. Required: projectId. - **get_single_hex_suggestion_by_id** — Get a single Hex context suggestion by id, including its evidence sources and proposed changes. Returns: id, title, summary, status, createdDate, lastSourceAddedDate, reviewAgentStatus, sources, proposedChanges. Required: id. - **update_a_hex_suggestion_by_id** — Update the status of a Hex context suggestion. Returns the updated suggestion object with its id, title, summary, status, createdDate, and reviewAgentStatus. Required: id, status. - **list_all_hex_suggestions** — List Hex context suggestions for the workspace. Returns: id, title, summary, status, createdDate, lastSourceAddedDate, reviewAgentStatus. Max 100 per page. - **update_a_hex_suggestion_change_by_id** — Update the status of an individual proposed change (a file or data-warehouse update) within a Hex context suggestion. Returns the updated suggestionUpdate object with its id, status, and rejectionReason. Required: id, suggestion_id, updateTarget, status. - **create_a_hex_suggestion_review** — Trigger a background review agent run for a context suggestion in Hex; if a review is already in flight for the suggestion, the current run is returned instead. Returns the suggestion including id, title, summary, status, createdDate, lastSourceAddedDate, and reviewAgentStatus. Required: suggestion_id. - **list_all_hex_threads** — List Hex agent threads in the workspace, sorted by most recently created first. Returns: title, creditsUsed, topics, warnings, feedback, warningsGeneratedAt, threadSummary, threadIntent, model, auto, effectiveModel, effortLevel, userId, type, classification, source, createdAt, updatedAt, sensitive, id, orgId, url. - **create_a_hex_thread** — Start a Hex agent thread with a prompt that the agent analyzes and responds to. Returns: threadId, url, createdAt, projectId. Required: prompt. The thread runs asynchronously — poll its status or visit the returned URL for progress; projectId and newProject are mutually exclusive. - **get_single_hex_thread_by_id** — Get the response of a Hex agent thread by id, including the agent's reply content when available. Returns: title, creditsUsed, topics, warnings, feedback, warningsGeneratedAt, threadSummary, threadIntent, model, auto, effectiveModel, threadId, status, url, resources, response, and 9 more. Required: id. Status is RUNNING, IDLE, or ERROR. - **create_a_hex_thread_followup** — Continue an existing Hex agent thread by sending a follow-up prompt. Returns: threadId, url. Required: thread_id, prompt. The thread must be idle before a follow-up can be sent — queuing is not supported. - **list_all_hex_me** — Get the currently logged-in Hex user. Returns: id, name, email, role, lastLoginDate, org, token. User metadata is omitted when authenticating with a workspace token. - **list_all_hex_users** — List all users in a Hex workspace. Returns: id, name, email, role, lastLoginDate. Max 500 per page. - **hex_users_deactivate** — Deactivate a user in Hex by id. Returns the deactivated user object including id, name, email, role, and lastLoginDate. Required: user_id. - **list_all_hex_context_topics** — List thread topics in the Hex workspace, sorted by name. Returns: topics, pagination. Max 100 per page. - **list_all_hex_draft_lists** — List draft guides in Hex. Returns: id, filePath. Max 100 per page. - **list_all_hex_thread_messages** — List messages in a Hex thread. Returns: type, text, createdAt. Required: thread_id. Max 50 per page. - **create_a_hex_semantic_projects_ingest** — Ingest a Hex semantic project from a zip file, triggering a sync of its semantic layer. Returns: traceId, contents, warnings, skipped, problems, debug. Required: semantic_project_id. - **update_a_hex_semantic_project_by_id** — Update statuses (including endorsements) on datasets and views within a Hex semantic project by id. Returns the batch result in updated. Atomic: if any update in the batch fails validation, the entire request fails and no changes are applied. Required: id, updates. ## How it works 1. **Link your customer's Hex account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Hex.** The Proxy API is a 1-to-1 mapping of the Hex API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Ship embedded analytics without building a BI engine** — Vertical SaaS platforms can offer their customers interactive, filterable dashboards inside their own product by embedding Hex apps. Truto handles the auth and API plumbing so you can focus on which data app to surface, not how to connect to Hex. - **Power conversational data agents inside your product** — Chat tools, copilots, and internal assistants can route natural language questions to Hex AI threads and return governed, semantic-layer-aware answers. This lets you offer trustworthy data Q&A without training your own analytics LLM. - **Build data lineage and observability for Hex users** — Data catalogs, observability platforms, and governance tools can map which warehouse tables feed which Hex projects, enabling blast-radius analysis for schema changes. Truto makes it fast to pull project metadata and queried tables across customer workspaces. - **Monitor Hex runs for security and compliance** — SIEM and DLP platforms can ingest Hex project run logs, flag anomalous executions, and even cancel suspicious runs programmatically. Offer your customers a unified audit trail across their analytics stack. - **Sync semantic definitions from your metrics layer** — If you provide a semantic layer, dbt-style metrics, or a metadata catalog, you can push definitions into Hex so AI responses stay aligned with approved business logic. Truto gives you a consistent interface to keep that context in sync. ## What you can build - **Signed embedded dashboards with row-level security** — Generate presigned Hex app URLs on the fly and pass user attributes so each end user sees only the data scoped to their account or tenant. - **Natural language data Q&A in chat or in-app** — Create Hex threads from user prompts, poll for completion, and return the AI agent's text answer alongside rendered chart images. - **Project lineage and blast-radius analysis** — List all Hex projects and the warehouse tables each one queries to power impact analysis when upstream schemas change. - **Automated chart delivery to email, Slack, or Teams** — Fetch rendered cell images from Hex projects and embed them in alerts, digests, or incident notifications sent through your platform. - **Centralized access and group governance** — Programmatically manage Hex users, groups, and sharing on collections, projects, and workspaces to mirror the permission model your customers already use. - **Run auditing and kill-switch controls** — Stream Hex project runs into your audit log, detect anomalous activity, and cancel in-flight runs via API when policies are violated. ## FAQs ### How does authentication to Hex work through Truto? Hex uses workspace-scoped API tokens. Your end users generate a token in their Hex workspace and provide it during the connection flow; Truto stores and rotates it, and every API call made on their behalf is scoped to that workspace. ### Can we securely embed Hex apps for our end users? Yes. You can call the Hex embedding presigned URL endpoint through Truto and pass user attributes, which Hex uses to enforce row-level security so each embedded session only exposes data for the authenticated end user. ### Does the integration support Hex's AI threads? Yes. You can create threads, post follow-up messages, retrieve thread state, and list thread messages, which is enough to build a full conversational analytics experience on top of a customer's Hex workspace. ### Can we pull chart images for notifications or reports? Yes. The integration exposes endpoints to fetch and search Hex cell images, which are returned as rendered assets you can attach to emails, Slack messages, or PDFs. ### What project execution controls are available? You can list and trigger project runs, fetch the status and metadata of a specific run, and delete (cancel) a run — useful for scheduling, retries, and security kill-switch workflows. ### How do we keep semantic context in Hex up to date from our platform? Hex exposes endpoints to ingest and update semantic projects, so if you own a metrics layer or catalog, you can push dataset definitions and status changes into Hex so its AI stays aligned with approved business logic. ### Is this integration already live, or built on request? Truto's Hex connector exposes the Hex REST API surface listed above. If you need additional endpoints or a specific normalized shape, Truto can extend the integration on request as part of onboarding.