Hex
Hex External API

The Hex External API for running projects, managing projects, collections, groups, cells, data connections, semantic models, agent Threads, and users.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.0.3",
  "info": {
    "title": "Hex 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": []
    }
  ],
  "paths": {
    "/v1/embedding/createPresignedUrl/{projectId}": {
      "post": {
        "operationId": "CreatePresignedUrl",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmbeddingResponse"
                }
              }
            }
          },
          "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": "Create an embedded url for a project",
        "parameters": [
          {
            "in": "path",
            "name": "projectId",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ProjectId"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingRequest"
              }
            }
          }
        }
      }
    },
    "/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.\n\nCreates a new project in the workspace with the specified title.\nOptionally 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"
              }
            }
          }
        }
      },
      "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"
            }
          }
        ]
      }
    },
    "/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"
            }
          }
        ]
      }
    },
    "/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.\nFor projects, use `CAN_VIEW` to grant the UI permission labeled \"Can explore\".\nUse `APP_ONLY` to grant the UI permission labeled \"Can view app\".\nWorkspace tokens calling this endpoint need to have \"Collections -> Write access\" scope\nin 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"
              }
            }
          }
        }
      }
    },
    "/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.\nFor projects, use `CAN_VIEW` to grant the UI permission labeled \"Can explore\".\nUse `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"
              }
            }
          }
        }
      }
    },
    "/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.\nFor projects, use `CAN_VIEW` to grant the UI permission labeled \"Can explore\".\nUse `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"
              }
            }
          }
        }
      }
    },
    "/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.\nFor projects, use `CAN_VIEW` to grant the UI permission labeled \"Can explore\".\nUse `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"
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}": {
      "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"
              }
            }
          }
        }
      },
      "get": {
        "operationId": "GetProject",
        "summary": "GetProject",
        "description": "Get metadata about a single project.\n\nThis endpoint is subject to the following rate limits:\n- `hex-api`: Default rate limit group for the Hex API\n  - Max requests per minute may vary (default: 30)\n  - Max requests per hour may vary (default: 1800)",
        "parameters": [
          {
            "in": "path",
            "name": "projectId",
            "description": "The project to fetch.",
            "schema": {
              "type": "string",
              "description": "The project to fetch."
            },
            "required": true
          },
          {
            "in": "query",
            "name": "includeSharing",
            "description": "Whether to include sharing metadata in the response.",
            "schema": {
              "type": "boolean",
              "default": false,
              "description": "Whether to include sharing metadata in the response."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string",
                      "nullable": true
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "PROJECT",
                        "COMPONENT"
                      ]
                    },
                    "creator": {
                      "type": "object",
                      "properties": {
                        "email": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "email"
                      ]
                    },
                    "owner": {
                      "type": "object",
                      "properties": {
                        "email": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "email"
                      ]
                    },
                    "status": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "name": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "name"
                      ]
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string",
                            "nullable": true
                          }
                        },
                        "required": [
                          "name",
                          "description"
                        ]
                      }
                    },
                    "reviews": {
                      "type": "object",
                      "properties": {
                        "required": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "required"
                      ]
                    },
                    "analytics": {
                      "type": "object",
                      "properties": {
                        "appViews": {
                          "type": "object",
                          "properties": {
                            "allTime": {
                              "type": "integer"
                            },
                            "lastSevenDays": {
                        

# --- truncated at 32 KB (345 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hex/refs/heads/main/openapi/hex-openapi-original.json
Hex External API

Documentation

Specifications

Other Resources

OpenAPI Specification
