### GET /v1/guides/draft/list

Source: https://learn.hex.tech/docs/api-integrations/api/reference

Retrieves a paginated list of all current guide drafts.

```APIDOC
## GET /v1/guides/draft/list

### Description
Fetches a paginated list of guide drafts available in the system.

### Method
GET

### Endpoint
https://app.hex.tech/api/v1/guides/draft/list

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of results to fetch (1-100, default 25)
- **after** (any) - Optional - Pagination cursor for next page
- **before** (any) - Optional - Pagination cursor for previous page
- **externalSource** (string) - Optional - JSON stringified, URI encoded external source locator

### Response
#### Success Response (200)
- **values** (array) - List of guide draft objects
- **pagination** (object) - Pagination metadata
- **traceId** (string) - Request trace identifier

#### Response Example
{
  "values": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "filePath": "string"
    }
  ],
  "pagination": {
    "after": "string",
    "before": "string"
  },
  "traceId": "string"
}
```

--------------------------------

### Install Hex CLI

Source: https://learn.hex.tech/docs/api-integrations/cli

Commands to install the Hex CLI tool on your local machine using Homebrew or a shell script installer.

```bash
brew install hex-inc/hex-cli/hex
```

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/hex-inc/hex-cli/releases/latest/download/hex-installer.sh | sh
```

--------------------------------

### Configure Hex Guides with JSON

Source: https://learn.hex.tech/docs/agent-management/context-management/guides

This JSON configuration file specifies which guides to upload to Hex. It supports direct paths, patterns for multiple files, and transformations like stripping folder structures. This file should be placed at the root of your GitHub repository.

```json
{
  "guides": [
    {
      "path": "path/to/my/guide.md"
    },
    {
      "path": "path_i_want_to_change.md",
      "hexFilePath": "path/that/will/show/up/in/hex.md"
    },
    {
      "pattern": "guides/*.md",
      "transform": {
        "stripFolders": true
      }
    },
    {
      "pattern": "guides/**/*.md"
    }
  ]
}
```

--------------------------------

### Importing Python Packages in Hex

Source: https://learn.hex.tech/docs/explore-data/cells/python-cells

Demonstrates how to import pre-installed Python packages and install new ones using `!uv pip install` within a Hex project. This allows for the use of external libraries to extend project functionality. Ensure the package is installed before importing.

```python
import pandas

print(pandas.DataFrame({'col1': [1, 2], 'col2': [3, 4]}))
```

```python
!uv pip install numpy
import numpy

print(numpy.array([1, 2, 3]))
```

--------------------------------

### Add GitHub Action for Hex Guide Publishing

Source: https://learn.hex.tech/docs/agent-management/context-management/guides

This YAML file defines a GitHub Actions workflow to automatically publish Hex guide files. It checks out the repository, uses the `hex-inc/action-context-toolkit` action, and requires a `HEX_API_TOKEN` secret for authentication. Optional parameters allow for automatic publishing and deletion of untracked guides.

```yaml
# .github/workflows/hex_context_toolkit.yml
name: Publish Hex context

on:
  push:
    branches: [ 'main', 'master' ]
  pull_request:

jobs:
  publish_hex_context:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v6
    - name: Upload guide files
      uses: hex-inc/action-context-toolkit@v1
      with:
        config_file: hex_context.config.json
        token: ${{ secrets.HEX_API_TOKEN }} # Create a workspace token with the Guides write scope and set this in your repository settings
        # optional configuration
        publish_guides: true # publish guides automatically (default true)
        delete_untracked_guides: true # removes guides from hex that were also deleted in your repository (default true)
        hex_url: https://app.hex.tech # For most Hex users, this will be https://app.hex.tech. For single tenant, EU multi tenant, and HIPAA multi tenant customers, replace app.hex.tech with your custom URL (e.g. atreides.hex.tech, eu.hex.tech).
```

--------------------------------

### Javascript Example for Embed API

Source: https://learn.hex.tech/docs/share-insights/embedding/signed-embedding

Example implementation of the Embed API request in Javascript using the `fetch` API.

```APIDOC
## Javascript Example for Embed API

### Description
This code snippet demonstrates how to make a POST request to the Embed API to generate a pre-signed URL using Javascript's `fetch` API.

### Method
POST

### Endpoint
`/embedding/createPresignedUrl/{PROJECT_ID}`

### Parameters
#### Path Parameters
- **PROJECT_ID** (string) - Required - The ID of the Hex project to embed.

#### Query Parameters
None

#### Request Body
- **hexUserAttributes** (object) - Optional - Attributes for row-level security.
- **scope** (array of strings) - Optional - Permissions for the embedded app.
- **expiresIn** (integer) - Optional - Validity duration of the URL in seconds.
- **displayOptions** (object) - Optional - Custom display settings for the iframe.

### Request Example
```javascript
const BASE_HEX_API_URL = "https://app.hex.tech/api/v1";
const TOKEN = "YOUR_WORKSPACE_TOKEN";
const PROJECT_ID = "YOUR_PROJECT_ID";

const body = {
  hexUserAttributes: {
    userId: "12345",
    userRole: "admin",
    userCountry: "MEX",
  },
  scope: ["EXPORT_PDF", "EXPORT_CSV"],
  expiresIn: 30000,
  displayOptions: {
    noEmbedFooter: true,
    noEmbedOutline: true,
    noEmbedBasePadding: true,
  },
};

fetch(`${BASE_HEX_API_URL}/embedding/createPresignedUrl/${PROJECT_ID}`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
})
  .then((response) => response.json())
  .then((data) => {
    console.log(data.url);
  })
  .catch((error) => {
    console.error("Error:", error);
  });
```

### Response
#### Success Response (200)
- **url** (string) - The pre-signed URL for embedding the Hex project.

#### Response Example
```json
{
  "url": "https://app.hex.tech/embed/abcdef1234567890"
}
```
```

--------------------------------

### Hex API Setup with Python Requests

Source: https://learn.hex.tech/docs/api-integrations/api/overview

Initializes the base URL, project ID, and authentication token for interacting with the Hex API using the requests library. Users need to replace placeholder values with their specific workspace URL, project ID, and API token. This setup is crucial for all subsequent API calls.

```python
import requests

# Single tenant, HIPAA, and EU users will need to replace this with their Hex URL
BASE_URL = 'https://app.hex.tech/api/v1'

# Replace this with the project ID
PROJECT_ID = '5a8591dd-4039-49df-9202-96385ba3eff8'

# Replace this with your token (format: hxtp_<96 hex chars> for personal, hxtw_<96 hex chars> for workspace)
TOKEN = 'hxtp_5bbf1c8b1989d6657d5c...'
```

--------------------------------

### POST /v1/guides/publish

Source: https://learn.hex.tech/docs/api-integrations/api/reference

Publishes all or specific draft guides to the platform.

```APIDOC
## POST /v1/guides/publish

### Description
Publishes currently drafted guides. Can publish all drafts or a specific subset by ID.

### Method
POST

### Endpoint
https://app.hex.tech/api/v1/guides/publish

### Parameters
#### Request Body
- **orgGuideFileIds** (array) - Optional - List of UUIDs to publish
- **publishAllDraftGuides** (boolean) - Required - If true, publishes all drafts

### Request Example
{
  "orgGuideFileIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
  "publishAllDraftGuides": true
}

### Response
#### Success Response (200)
- **message** (string) - Status message
- **publishedGuides** (array) - List of successfully published guides
- **traceId** (string) - Request trace identifier

#### Response Example
{
  "message": "success",
  "publishedGuides": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "filePath": "string"
    }
  ],
  "traceId": "string"
}
```

--------------------------------

### Initialize SSH Directory and Permissions

Source: https://learn.hex.tech/docs/connect-to-data/data-connections/connect-via-ssh

Commands to set up the .ssh directory and authorized_keys file with secure permissions for the hex user.

```bash
mkdir ~/.ssh
chmod 700 ~/.ssh
cd ~/.ssh
touch authorized_keys
chmod 600 authorized_keys
```

--------------------------------

### Analyzing SQL Query Results with R

Source: https://learn.hex.tech/docs/explore-data/cells/r-support

Shows how to reference SQL query results stored in a dataframe within an R cell to perform further analysis. This example calculates the distance between starting and ending stations for each trip using the 'citibike_data' dataframe.

```R
# Assuming 'citibike_data' is a dataframe populated from a SQL query
citibike_data$trip_distance <- sqrt(citibike_data$start_station_x^2 + citibike_data$start_station_y^2)
print(head(citibike_data))
```

--------------------------------

### Access Hex CLI Help Documentation

Source: https://learn.hex.tech/docs/api-integrations/cli

Commands to display the CLI help menu and view documentation for specific subcommands.

```bash
hex --help
hex auth --help
```

--------------------------------

### Parameterizing SQL Queries with Jinja

Source: https://learn.hex.tech/docs/explore-data/cells/using-jinja

Demonstrates how to inject Python variables into SQL queries using Jinja syntax. Includes examples for standard value substitution, array handling, and literal parameterization using the sqlsafe flag.

```sql
-- Standard variable substitution
SELECT * FROM table WHERE column = {{value}};

-- Array variable substitution
SELECT * FROM table WHERE id IN {{list_variable | array}};

-- Forcing literal parameterization for column names
SELECT * FROM table WHERE {{column | sqlsafe}} = 'some_value';
```

--------------------------------

### Publish Guide Drafts Request

Source: https://learn.hex.tech/docs/api-integrations/api/reference

Payload structure for publishing draft guides. Users can specify a list of guide IDs or set publishAllDraftGuides to true to publish everything.

```json
{
  "orgGuideFileIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "publishAllDraftGuides": true
}
```

--------------------------------

### Upsert Guide Draft Request

Source: https://learn.hex.tech/docs/api-integrations/api/reference

Payload structure for creating or updating guide drafts. It supports a forceWrite flag to overwrite existing guides and a list of file objects.

```json
{
  "forceWrite": true,
  "files": [
    {
      "externalSource": {
        "id": "string",
        "source": "unknown"
      },
      "contents": "string",
      "filePath": "string",
      "property1": null,
      "property2": null
    }
  ]
}
```

--------------------------------

### List All Files in Hex Project Directory (Python)

Source: https://learn.hex.tech/docs/explore-data/projects/environment-configuration/files

Recursively walks through the current directory and its subdirectories to print the path of all files present in the Hex project. This helps in understanding the project's file structure.

```python
from os import walk
from pathlib import PurePath
for path, subdirs, files in walk('.'):
    for name in files:
        print(PurePath(path, name))
```

--------------------------------

### Delete Draft Guide

Source: https://learn.hex.tech/docs/api-integrations/api/reference

Deletes a draft version of a guide file from a project.

```APIDOC
## DELETE /v1/guides/draft/{orgGuideFileId}

### Description
Deletes a draft version of a guide file.

### Method
DELETE

### Endpoint
/v1/guides/draft/{orgGuideFileId}

### Parameters
#### Path Parameters
- **orgGuideFileId** (string) - Required - 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
#### Success Response (204)
No content returned on successful deletion.

#### Error Response (400, 403, 500)
- **details** (string) - Description of the error.
- **traceId** (string) - Unique identifier for the request trace.
- **reason** (string) - The reason for the error.
```

--------------------------------

### Install Python Packages via Terminal

Source: https://learn.hex.tech/docs/explore-data/projects/environment-configuration/using-packages

Use pip or the faster uv tool to install external Python packages. Note that these installations are temporary and must be re-run upon kernel restart.

```python
!pip install astropy
```

```python
!uv pip install astropy
```

--------------------------------

### Guide Frontmatter Definition (Markdown)

Source: https://learn.hex.tech/docs/agent-management/context-management/guides

Defines metadata for a Hex guide, including its name and a brief description. This frontmatter helps the Hex Agent determine the guide's relevance to specific conversations or tasks.

```markdown
---
name: Customers
description: Understanding Hex's types of customers
---

...
```

--------------------------------

### Loading an R Library

Source: https://learn.hex.tech/docs/explore-data/cells/r-support

Demonstrates how to load a pre-installed R library or install and load a new one within an R project in Hex. This is essential for utilizing specific R packages for data analysis and visualization.

```R
library(ggplot2)
# Or to install and load a new library:
# install.packages("plotly")
# library(plotly)
```

--------------------------------

### Python Example for Embed API

Source: https://learn.hex.tech/docs/share-insights/embedding/signed-embedding

Example implementation of the Embed API request in Python using the `requests` library.

```APIDOC
## Python Example for Embed API

### Description
This code snippet demonstrates how to make a POST request to the Embed API to generate a pre-signed URL using Python.

### Method
POST

### Endpoint
`/embedding/createPresignedUrl/{PROJECT_ID}`

### Parameters
#### Path Parameters
- **PROJECT_ID** (string) - Required - The ID of the Hex project to embed.

#### Query Parameters
None

#### Request Body
- **hexUserAttributes** (object) - Optional - Attributes for row-level security.
- **scope** (array of strings) - Optional - Permissions for the embedded app.
- **expiresIn** (integer) - Optional - Validity duration of the URL in seconds.
- **displayOptions** (object) - Optional - Custom display settings for the iframe.

### Request Example
```python
import requests

BASE_HEX_API_URL = 'https://app.hex.tech/api/v1'
TOKEN = 'YOUR_WORKSPACE_TOKEN'
PROJECT_ID = 'YOUR_PROJECT_ID'

body = {
  "hexUserAttributes": {
    "userId": "12345",
    "userRole": "admin",
    "userCountry": "MEX"
  },
  "scope": ["EXPORT_PDF", "EXPORT_CSV"],
  "expiresIn": 30000,
  "displayOptions": {
    "noEmbedFooter": true,
    "noEmbedOutline": true,
    "noEmbedBasePadding": true
  }
}

response = requests.post(
url=f"{BASE_HEX_API_URL}/embedding/createPresignedUrl/{PROJECT_ID}",
json=body, headers={"Authorization" : f"Bearer {TOKEN}"}
)

print(response.json().get("url"))
```

### Response
#### Success Response (200)
- **url** (string) - The pre-signed URL for embedding the Hex project.

#### Response Example
```json
{
  "url": "https://app.hex.tech/embed/abcdef1234567890"
}
```
```

--------------------------------

### List Guide Drafts Request

Source: https://learn.hex.tech/docs/api-integrations/api/reference

Represents the JSON structure for the response when listing draft guides. It includes a list of file values and pagination metadata.

```json
{
  "values": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "filePath": "string"
    }
  ],
  "pagination": {
    "after": "string",
    "before": "string"
  },
  "traceId": "string"
}
```

--------------------------------

### Create Collection with Permissions

Source: https://learn.hex.tech/docs/api-integrations/api/overview

Initializes a new collection while defining access levels for specific groups and the entire workspace. Requires admin privileges for group and workspace-level access configuration.

```python
collection_payload = {  
    "name": "Q3 Projects",  
    "description": "All Q3 cross-functional initiatives",  
    "members": {  
        "groups": [  
            {"id": "group-analytics", "access": "MEMBER"},  
            {"id": "group-admins", "access": "MANAGER"}  
        ],  
        "workspace": {"members": "MEMBER"}  
    }  
}  
  
resp = requests.post(  
    url=f"{BASE_URL}/collections",  
    json=collection_payload,  
    headers={"Authorization": f"Bearer {YOUR_API_TOKEN}"}  
)
```

--------------------------------

### Import Hex Public Key

Source: https://learn.hex.tech/docs/connect-to-data/data-connections/connect-via-ssh

Command to append the Hex workspace public key to the authorized_keys file on the bastion host.

```bash
echo "<PUBLIC KEY>" >> ~/.ssh/authorized_keys
```

--------------------------------

### Get Group Information

Source: https://learn.hex.tech/docs/api-integrations/api/reference

Retrieves details for a specific group using its groupId. This is a GET request to the /v1/groups/{groupId} endpoint. It returns group information including id, name, and createdAt.

```HTTP
GET /v1/groups/{groupId} HTTP/1.1
Host: app.hex.tech
```

--------------------------------

### PUT /v1/guides/draft

Source: https://learn.hex.tech/docs/api-integrations/api/reference

Updates or creates guide drafts based on provided file paths and content.

```APIDOC
## PUT /v1/guides/draft

### Description
Updates or creates guide drafts. If the guide doesn't exist, it is created; if it exists, the draft is updated.

### Method
PUT

### Endpoint
https://app.hex.tech/api/v1/guides/draft

### Parameters
#### Request Body
- **forceWrite** (boolean) - Optional - Overwrite existing guides synced from different sources
- **files** (array) - Required - Mapping from filePath to contents

### Request Example
{
  "forceWrite": true,
  "files": [
    {
      "contents": "string",
      "filePath": "string"
    }
  ]
}

### Response
#### Success Response (200)
- **files** (array) - List of updated/created file IDs
- **warnings** (array) - List of any processing warnings
- **traceId** (string) - Request trace identifier

#### Response Example
{
  "files": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "filePath": "string"
    }
  ],
  "warnings": [],
  "traceId": "string"
}
```