gotoHuman

https://docs.gotohuman.com/
Admin
gotoHuman is a platform that enables human supervisors to review AI-generated content, approve AI...
Tokens:16,901
Snippets:69
Trust Score:6.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install and Initialize Python SDK for gotoHuman

Source: https://docs.gotohuman.com/send-requests

Install the gotoHuman Python SDK using pip and set up your API key via an environment variable. Initialize the SDK for use in your application. Ensure you have the 'dotenv' library if using a .env file.

```bash
pip install gotohuman
```

```text
GOTOHUMAN_API_KEY=YOUR_API_KEY
```

```python
from dotenv import load_dotenv
load_dotenv()

gotoHuman = GotoHuman()
```

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

### Install and Initialize JavaScript/TypeScript SDK for gotoHuman

Source: https://docs.gotohuman.com/send-requests

Install the gotoHuman JavaScript/TypeScript SDK using npm and initialize it with your API key. The API key should be provided during initialization or via an environment variable.

```bash
npm i gotohuman
```

```javascript
const GOTOHUMAN_API_KEY = process.env.GOTOHUMAN_API_KEY;
const gotoHuman = new GotoHuman(GOTOHUMAN_API_KEY);
```

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

### Installing gotoHuman n8n Node from npm

Source: https://docs.gotohuman.com/Integrations/n8n

Instructions for installing the gotoHuman n8n node manually from npm for self-hosted n8n instances. This is an alternative method if the node is not found in the n8n nodes panel.

```bash
@gotohuman/n8n-nodes-gotohuman  

```

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

### Use Training Data in AI Prompts (Python)

Source: https://context7.com/context7/gotohuman/llms.txt

Integrate approved review data fetched from Gotohuman as few-shot examples to improve AI generation quality. This Python script first fetches training data using the `requests` library and then constructs a prompt for an OpenAI model, incorporating the fetched examples to guide the AI's output.

```python
import requests
from openai import OpenAI

# Fetch training data
response = requests.get(
    'https://api.gotohuman.com/queryResponses',
    headers={'x-api-key': 'YOUR_API_KEY'},
    params={
        'formId': 'form123',
        'fieldIds': 'emailDraft',
        'approvedValuesOnly': 'true',
        'limit': 10
    }
)
training_examples = response.json()

# Build few-shot prompt
examples_text = "\n\n".join([
    f"Example {i+1}:\n{ex['emailDraft']}"
    for i, ex in enumerate(training_examples)
])

# Generate with examples
client = OpenAI()
completion = client.chat.completions.create(
    model="gpt-4",
    messages=[{
        "role": "user",
        "content": f"""Generate a personalized outreach email for a new prospect.

Here are examples of approved emails:

{examples_text}

Prospect information:
Name: Alex Chen
Company: TechStartup Inc
Context: They recently launched a new AI product

Generate the email:"""
    }]
)

generated_email = completion.choices[0].message.content
print(generated_email)
```

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

### Configure gotoHuman MCP Server for Cursor/Claude/Windsurf

Source: https://docs.gotohuman.com/mcp-server

This JSON configuration snippet shows how to set up the gotoHuman MCP server within your project. It specifies the command to run, arguments for installation, and environment variables like the API key required for authentication.

```json
{
  "mcpServers": {
    "gotoHuman": {
      "command": "npx",
      "args": ["-y", "@gotohuman/mcp-server"],
      "env": {
        "GOTOHUMAN_API_KEY": "your-api-key"
      }
    }
  }
}
```

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

### Fetch Human Review Data via API

Source: https://docs.gotohuman.com/training-data

This code snippet demonstrates how to construct a GET request to the /queryResponses endpoint to fetch human review data. It includes the necessary authentication header and query parameters like formId, fieldIds, and optional filters. The example URL shows a practical application of these parameters.

```HTTP
GET https://api.gotohuman.com/queryResponses

Auth Header:
x-api-key: YOUR_API_KEY

Query Parameters:
  * `formId` (string, **required**): The ID of the review template / form.
  * `fieldIds` (string, **required**): The comma-separated IDs of the fields you are interested in.
  * `filterResponse` (string, _optional_): Filter by review status. Possible values: `approved`, `rejected`.
  * `groupByField` (boolean, _optional_ , default: `false`): Whether to group the responses by field. If not, grouped by review.
  * `approvedValuesOnly` (boolean, _optional_ , default: `false`): Lists only the response values for approved reviews.
  * `rejectedValuesOnly` (boolean, _optional_ , default: `false`): Lists only the request values for rejected reviews.
  * `limit` (number, _optional_ , default: `20`, max: `500` (free plan: `20`)): The number of responses to return.

Example:
https://api.gotohuman.com/queryResponses?formId=FORM_ID&fieldIds=FIELD_ID1,FIELD_ID2&filterResponse=approved
```

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

### Create Review

Source: https://docs.gotohuman.com/send-requests

This section details how to create a review and add field data using Python and JavaScript SDKs, along with an example of the raw JSON request.

```APIDOC
## POST /api/reviews

### Description
Creates a new review and allows adding field data for various components like URL links and text.

### Method
POST

### Endpoint
/api/reviews

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **formId** (string) - Required - The ID of the review template.
- **fields** (object) - Required - An object containing field IDs and their corresponding data.
  - **fieldName** (object|string) - Required - Data for the specific field. Can be an object with `label` and `url` for URL fields, or a string for text fields.

### Request Example
```json
{
  "formId": "abcdef12345",
  "fields": {
    "linkedin": {
      "label": "Rodrigo G.",
      "url": "https://www.linkedin.com/in/rodrigog12/"
    },
    "aiDraft": "Hey there, I saw..."
  }
}
```

### Response
#### Success Response (200)
- **reviewId** (string) - The ID of the created review.
- **status** (string) - The status of the review creation.

#### Response Example
```json
{
  "reviewId": "review-12345",
  "status": "created"
}
```
```

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

### LLM Prompting with Training Data

Source: https://docs.gotohuman.com/training-data

This example illustrates how to integrate fetched training data into an LLM prompt. It shows how to use template literals to insert dynamic data, such as `${trainingData.yourFieldId1}`, into a prompt designed to generate personalized outputs based on historical human reviews.

```String Template
Please generate a personalized email for a new prospect based on the following information:
  
// context  
  
Look at the following examples to generate the email:  
  
${trainingData.yourFieldId1}
```

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

### Send Images for Review with CDN Caching (Bash)

Source: https://context7.com/context7/gotohuman/llms.txt

This example shows how to use `curl` to send images for review, leveraging GotoHuman's automatic CDN caching. It includes options for resizing and cropping images, and illustrates the structure of the webhook response containing cached URLs.

```bash
curl -X POST https://api.gotohuman.com/requestReview \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ \
    "formId": "form123", \
    "fields": { \
      "imageOptions": { \
        "options": [ \
          { "url": "https://files.oaiusercontent.com/temp-image-1.jpg" }, \
          { "url": "https://files.oaiusercontent.com/temp-image-2.jpg" } \
        ], \
        "config": { \
          "resize": { \
            "width": 1080, \
            "height": 1920, \
            "fit": "cover", \
            "position": "centre" \
          } \
        } \
      } \
    } \
  }'
```

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

### Configure Selectable Options and Defaults (Python SDK)

Source: https://docs.gotohuman.com/send-requests

Example of how to define selectable options and a default selection for form fields like buttons, checkboxes, or dropdowns using the Python SDK. This allows for pre-configured choices.

```python
review.add_field_data("buttons", {
    "options": [
        {
            "id": "choice1",
            "label": "Choice 1"
        },
        {
            "id": "choice2",
            "label": "Choice 2"
        }
    ],
    "default": "choice2"
})
```

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

### Add Workflow Metadata (Python SDK Example)

Source: https://docs.gotohuman.com/send-requests

This Python code demonstrates how to add workflow metadata using the GoToHuman SDK. It utilizes the `add_meta_data` method to include the workflow run information.

```python
review.add_meta_data("_gthWorkflow", {
    "runId": "1234567890",
    "runName": "My Workflow",
    "prevSteps": [
      "1234567890"
    ]
  })
```

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

### Query Approved Training Data (Bash)

Source: https://context7.com/context7/gotohuman/llms.txt

Retrieve approved review and edit data for use as few-shot examples in AI prompts. This `curl` command demonstrates fetching data for specific fields, filtering by response status, and optionally retrieving only the approved values. It's useful for self-learning and improving AI model performance.

```bash
# Fetch approved review data for specific fields
curl -G https://api.gotohuman.com/queryResponses \
  -H "x-api-key: YOUR_API_KEY" \
  -d "formId=form123" \
  -d "fieldIds=emailDraft,subject" \
  -d "filterResponse=approved" \
  -d "limit=50"

# Response grouped by review:
# [
#   {
#     "reviewId": "abc123",
#     "createdAt": "2025-03-12T22:25:42.415Z",
#     "respondedAt": "2025-03-12T22:26:15.253Z",
#     "response": "approved",
#     "fields": {
#       "emailDraft": {
#         "suggestedValue": "Hi Lenny, I saw the news...",
#         "approvedValue": "Hello Lenny, I tested your latest model..."
#       },
#       "subject": {
#         "suggestedValue": "Quick question about your product",
#         "approvedValue": "Exciting collaboration opportunity"
#       }
#     }
#   }
# ]

# Get only approved values for prompt examples
curl -G https://api.gotohuman.com/queryResponses \
  -H "x-api-key: YOUR_API_KEY" \
  -d "formId=form123" \
  -d "fieldIds=emailDraft" \
  -d "approvedValuesOnly=true" \
  -d "limit=100"

# Response with values only:
# [
#   { "emailDraft": "Hello Lenny, I tested your latest model..." },
#   { "emailDraft": "Hi Sarah, I came across your recent post..." }
# ]
```

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

### Add Workflow Metadata (JSON Example)

Source: https://docs.gotohuman.com/send-requests

This JSON structure is used to send workflow metadata, including a unique run ID, an optional run name, and previous step review IDs, to the GoToHuman API.

```json
{
  "_gthWorkflow": {
    "runId": "1234567890",
    "runName": "My Workflow",
    "prevSteps": [
      "1234567890"
    ]
  }
}
```

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

### Add Workflow Metadata (JS/TS SDK Example)

Source: https://docs.gotohuman.com/send-requests

This JavaScript/TypeScript code snippet shows how to add workflow metadata using the GoToHuman SDK. The `addMetaData` method is used to pass the workflow details.

```javascript
reviewRequest.addMetaData("_gthWorkflow", {
    "runId": "1234567890",
    "runName": "My Workflow",
    "prevSteps": [
      "1234567890"
    ]
  })
```

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

### Referencing Previous Node Data in n8n Expression

Source: https://docs.gotohuman.com/Integrations/n8n

Example of how to reference data from a previous node within an n8n expression. This is useful for dynamically populating fields in the gotoHuman review, such as URLs and labels for a 'Links' field which expects an array of objects.

```javascript
// Expression:  
{{		  			  			[{  					url: $("LeadGenParams").item.json.url,  					label: "Analyzed Website"  					}]  				}}


```

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

### Set Dynamic Form Options with Defaults (TypeScript)

Source: https://context7.com/context7/gotohuman/llms.txt

Dynamically set selectable options for form elements like buttons, checkboxes, or dropdowns. This example shows how to provide options and preselect default values, including multiple defaults for checkbox groups. It uses the gotoHuman library to create and configure a review request.

```typescript
const reviewRequest = gotoHuman.createReview('form123')
  .addFieldData('statusButtons', {
    options: [
      { id: 'draft', label: 'Keep as Draft' },
      { id: 'schedule', label: 'Schedule Publishing' },
      { id: 'publish', label: 'Publish Now' }
    ],
    default: 'schedule'
  })
  .addFieldData('categories', {
    options: [
      { id: 'tech', label: 'Technology' },
      { id: 'business', label: 'Business' },
      { id: 'ai', label: 'Artificial Intelligence' }
    ],
    default: ['tech', 'ai']  // Multiple defaults for checkboxes
  });

await reviewRequest.sendRequest();
```

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

### Review Submission Webhook Payload Example (JSON)

Source: https://docs.gotohuman.com/webhooks

This JSON object represents the data structure sent via a POST request to your configured webhook URL when a review is submitted. The 'responseValues' and 'meta' fields are dynamic and depend on your review template configuration and request metadata. The Content-Type header is 'application/json'.

```json
{
    "type": "review",
    "accountId": "abFMvLv4HafQymWxKDAov",
    "formId": "123456abcdef",
    "formName": "Review AI Draft",
    "reviewId": "123456abcdef",
    "response": "approved",
    "respondingUser": "user@email.com",
    "respondedAt": "2024-10-05T14:48:00.000Z",
    "responseValues": {
        "blogPost": {
            "value": "Regarding the very interesting topic of...",
            "wasEdited": true
        },
        "rating": {
            "value": 7.5,
            "wasEdited": false
        },
        "decisionSelect": {
            "value": "approve"
        }
    },
    "meta": {
        "example": "LLM thread id"
    },
    "gthLinkToReview": "https://app.gotohuman.com/accounts/abFMvLv4HafQymWxKDAov/ReviewRequests/123456abcdef"
}
```

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

### Python SDK - Create Review

Source: https://context7.com/context7/gotohuman/llms.txt

Initialize the SDK and create a review request with field data and metadata.

```APIDOC
## Python SDK - Create Review

### Description
Initialize the SDK and create a review request with field data and metadata using the Python SDK.

### Method
Uses the `gotohuman` Python library.

### Endpoint
N/A (SDK abstraction)

### Parameters
#### Environment Variables
- **GOTOHUMAN_API_KEY** (string) - Required - Your gotoHuman API key.

#### SDK Usage
- **`GotoHuman()`**: Initializes the SDK.
- **`create_review(formId)`**: Creates a review object with the specified form ID.
- **`add_field_data(field_name, value)`**: Adds data for a specific form field.
- **`add_meta_data(key, value)`**: Adds metadata to the review request.
- **`assign_to_users(email_list)`**: Assigns the review to a list of users by email.
- **`send_request()`**: Sends the review request to the API.

### Request Example
```python
from gotohuman import GotoHuman
from dotenv import load_dotenv

load_dotenv()

# Initialize SDK (reads GOTOHUMAN_API_KEY from environment)
gotoHuman = GotoHuman()

# Create review with field data
review = gotoHuman.create_review("abcdef12345")
review.add_field_data("linkedin", {
    "label": "Rodrigo G.",
    "url": "https://www.linkedin.com/in/rodrigog12/"
})
review.add_field_data("aiDraft", "Hey there, I saw your latest model...")
review.add_meta_data("threadId", "oai-thread-443289")
review.assign_to_users(["jess@acme.org"])

try:
    response = review.send_request()
    print(f"Review sent successfully: {response['reviewId']}")
    print(f"Review link: {response['gthLink']}")
except Exception as e:
    print(f"Error occurred: {e}")
```

### Response
#### Success Response
- **reviewId** (string) - The ID of the created review.
- **gthLink** (string) - A direct link to the review in the gotoHuman app.

#### Response Example
(See Request Example for output)
```

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

### Upload Binary Files for Review (Bash)

Source: https://context7.com/context7/gotohuman/llms.txt

This bash script demonstrates how to upload binary files, such as images and videos, using `curl` before creating a review request. It includes an option to specify resizing configurations for uploaded images and indicates that the response will contain URLs to be used in subsequent review requests.

```bash
curl -X POST https://api.gotohuman.com/uploadFiles \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file1=@/path/to/image.jpg" \
  -F "file2=@/path/to/video.mp4" \
  -F 'config={"resize":{"width":800,"height":600,"fit":"contain"}}'
```

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

### Image Editing Options

Source: https://docs.gotohuman.com/send-requests

Explains how to use the `config` object within the request body to enable on-the-fly image resizing and cropping.

```APIDOC
## Image Editing Configuration

### Description
Configure on-the-fly image resizing and cropping for image fields by including a `config` object with resize options in the request body.

### Request Body Example (within a review creation request)
```json
{
  "fields": {
    "imageFieldId": {
      "options": [
        {
          "url": "https://www.imgs.com/img.jpg"
        },
        {
          "url": "https://www.imgs.com/img2.jpg"
        }
      ],
      "config": {
        "resize": {
          "width": 400,
          "height": 800,
          "fit": "cover"
        }
      }
    },
    ...
  },
  ...
}
```

### Resize Options
- **width** (integer) - Target width in pixels.
- **height** (integer) - Target height in pixels.
- **fit** (string) - How to fit the image (`cover`, `contain`, `fill`, `inside`, `outside`).
- **position** (string) - Where to position the image when using `cover` or `contain` (`top`, `right top`, `right`, `right bottom`, `bottom`, `left bottom`, `left`, `left top`, `centre`).
- **background** (string|object) - Background color for `contain` fit (e.g., `"#ffffff"`, `"red"`, `{r: 255, g: 0, b: 0, alpha: 1}`).
- **withoutEnlargement** (boolean) - Prevent upscaling.
- **withoutReduction** (boolean) - Prevent downscaling.
```

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

### Get Nested Field Value from Review Response in Make

Source: https://docs.gotohuman.com/Integrations/make-com

This snippet demonstrates how to access a specific field's value from the 'Response Values' collection in Make. It shows two common methods: direct mapping and using the 'get' function for nested values. This is useful for extracting specific data points after a human review is submitted.

```Make
get([Response Values]; yourFormFieldId.value)
```

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

### Upload Files

Source: https://docs.gotohuman.com/send-requests

Details on how to upload binary files directly using a POST request to the `uploadFiles` endpoint.

```APIDOC
## POST /uploadFiles

### Description
Upload binary files directly to GoToHuman. This endpoint is used before creating a review to handle direct file uploads.

### Method
POST

### Endpoint
https://api.gotohuman.com/uploadFiles

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file** (file) - Required - The binary file to upload.
- **config** (object) - Optional - Configuration for image editing options.

### Request Example
(Binary file upload, refer to SDKs or tools like cURL for multipart/form-data)

### Response
#### Success Response (200)
- **fileUrl** (string) - The URL of the uploaded file.
- **cdnUrl** (string) - The CDN URL for the uploaded file.

#### Response Example
```json
{
  "fileUrl": "https://storage.gotohuman.com/uploads/file.jpg",
  "cdnUrl": "https://cdn1.gotohuman.com/uploads/file.jpg"
}
```
```

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

### Create Review Request using Python SDK

Source: https://context7.com/context7/gotohuman/llms.txt

Utilize the gotoHuman Python SDK to initialize the client and create a review request. This involves adding field data, metadata, and assigning users before sending the request. The SDK handles API interactions and error handling.

```python
from gotohuman import GotoHuman
from dotenv import load_dotenv

load_dotenv()

# Initialize SDK (reads GOTOHUMAN_API_KEY from environment)
gotoHuman = GotoHuman()

# Create review with field data
review = gotoHuman.create_review("abcdef12345")
review.add_field_data("linkedin", {
    "label": "Rodrigo G.",
    "url": "https://www.linkedin.com/in/rodrigog12/"
})
review.add_field_data("aiDraft", "Hey there, I saw your latest model...")
review.add_meta_data("threadId", "oai-thread-443289")
review.assign_to_users(["jess@acme.org"])

try:
    response = review.send_request()
    print(f"Review sent successfully: {response['reviewId']}")
    print(f"Review link: {response['gthLink']}")
except Exception as e:
    print(f"Error occurred: {e}")
```

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

### POST /requestReview

Source: https://context7.com/context7/gotohuman/llms.txt

Submits a review request, supporting image uploads with automatic CDN caching, resizing, and cropping.

```APIDOC
## POST /requestReview

### Description
Send images for review with automatic CDN caching and optional resizing/cropping. This endpoint allows for efficient handling of media assets intended for review.

### Method
POST

### Endpoint
/requestReview

### Parameters
#### Request Body
- **formId** (string) - Required - The ID of the form to be used for the review.
- **fields** (object) - Required - An object containing the fields for the review request.
  - **imageOptions** (object) - Required - Configuration for image handling.
    - **options** (array) - Required - A list of image objects.
      - **url** (string) - Required - The URL of the image to be processed.
    - **config** (object) - Optional - Configuration for image manipulation.
      - **resize** (object) - Optional - Parameters for resizing the image.
        - **width** (integer) - Optional - The target width for resizing.
        - **height** (integer) - Optional - The target height for resizing.
        - **fit** (string) - Optional - The resizing fit mode (e.g., 'cover', 'contain').
        - **position** (string) - Optional - The cropping position (e.g., 'centre').

### Request Example
```json
{
  "formId": "form123",
  "fields": {
    "imageOptions": {
      "options": [
        { "url": "https://files.oaiusercontent.com/temp-image-1.jpg" },
        { "url": "https://files.oaiusercontent.com/temp-image-2.jpg" }
      ],
      "config": {
        "resize": {
          "width": 1080,
          "height": 1920,
          "fit": "cover",
          "position": "centre"
        }
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **responseValues** (object) - Contains the processed image URLs and their review status.
  - **imageOptions** (object) - Details about the processed images.
    - **selected** (array of strings) - URLs of the selected or processed images.
    - **value** (array of objects) - Array of objects, each containing original URL, cached URL, and review response.
      - **originalUrl** (string) - The original URL of the image.
      - **url** (string) - The CDN-cached URL of the image.
      - **response** (string|null) - The review response for the image (e.g., 'approved').

#### Response Example
```json
{
  "responseValues": {
    "imageOptions": {
      "selected": ["https://cdn1.gotohuman.com/cached-image-2.jpg"],
      "value": [
        {
          "originalUrl": "https://files.oaiusercontent.com/temp-image-1.jpg",
          "url": "https://cdn1.gotohuman.com/cached-image-1.jpg",
          "response": null
        },
        {
          "originalUrl": "https://files.oaiusercontent.com/temp-image-2.jpg",
          "url": "https://cdn1.gotohuman.com/cached-image-2.jpg",
          "response": "approved"
        }
      ]
    }
  }
}
```
```

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

### JavaScript/TypeScript SDK - Create Review

Source: https://context7.com/context7/gotohuman/llms.txt

Create and send a review request using the TypeScript SDK with chained methods.

```APIDOC
## JavaScript/TypeScript SDK - Create Review

### Description
Create and send a review request using the TypeScript SDK with chained methods for a fluent API experience.

### Method
Uses the `gotohuman` TypeScript library.

### Endpoint
N/A (SDK abstraction)

### Parameters
#### Environment Variables
- **GOTOHUMAN_API_KEY** (string) - Required - Your gotoHuman API key.

#### SDK Usage
- **`new GotoHuman(apiKey)`**: Initializes the SDK with your API key.
- **`createReview(formId)`**: Initiates a new review request with the specified form ID.
- **`addFieldData(fieldName, value)`**: Adds data for a specific form field. Can be chained.
- **`addMetaData(key, value)`**: Adds metadata to the review request. Can be chained.
- **`assignToUsers(emailList)`**: Assigns the review to a list of users by email. Can be chained.
- **`sendRequest()`**: Sends the review request to the API. Returns a Promise.

### Request Example
```typescript
import { GotoHuman } from 'gotohuman';

const gotoHuman = new GotoHuman(process.env.GOTOHUMAN_API_KEY);

const reviewRequest = gotoHuman.createReview('abcdef12345')
  .addFieldData('linkedin', {
    label: 'Rodrigo G.',
    url: 'https://www.linkedin.com/in/rodrigog12/'
  })
  .addFieldData('aiDraft', 'Hey there, I saw your latest model...')
  .addMetaData('threadId', 'oai-thread-443289')
  .assignToUsers(['jess@acme.org']);

try {
  const response = await reviewRequest.sendRequest();
  console.log(`Review ID: ${response.reviewId}`);
  console.log(`Review link: ${response.gthLink}`);
} catch (error) {
  console.error('Failed to send review:', error);
}
```

### Response
#### Success Response
- **reviewId** (string) - The ID of the created review.
- **gthLink** (string) - A direct link to the review in the gotoHuman app.

#### Response Example
(See Request Example for output)
```

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

### POST /uploadFiles

Source: https://context7.com/context7/gotohuman/llms.txt

Uploads binary files (images, videos) to be used in review requests. This is a prerequisite for including these files in a review.

```APIDOC
## POST /uploadFiles

### Description
Upload binary image or video files before creating a review request. The returned URLs can then be used within the review request's fields.

### Method
POST

### Endpoint
/uploadFiles

### Parameters
#### Request Body
- **file1** (binary) - Required - The first file to upload (e.g., an image).
- **file2** (binary) - Optional - A second file to upload (e.g., a video).
- **config** (JSON string) - Optional - Configuration options for file processing, such as resizing.
  - **resize** (object) - Optional - Parameters for resizing images.
    - **width** (integer) - Optional - The target width.
    - **height** (integer) - Optional - The target height.
    - **fit** (string) - Optional - The resizing fit mode (e.g., 'contain').

### Request Example
```bash
curl -X POST https://api.gotohuman.com/uploadFiles \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file1=@/path/to/image.jpg" \
  -F "file2=@/path/to/video.mp4" \
  -F 'config={"resize":{"width":800,"height":600,"fit":"contain"}}'
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating successful upload.
- **urls** (array of strings) - A list of URLs pointing to the uploaded and processed files. These URLs should be used in subsequent review requests.

#### Response Example
```json
{
  "message": "Files uploaded successfully.",
  "urls": [
    "https://cdn.gotohuman.com/processed/image.jpg",
    "https://cdn.gotohuman.com/processed/video.mp4"
  ]
}
```
```

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

### AI Retry Webhook Payload Example

Source: https://docs.gotohuman.com/retries

This JSON payload represents the data received by a webhook when a reviewer requests an AI retry or edits a prompt. It includes event details, review identifiers, and the message content, which in this case is the initial human prompt. This data is crucial for your backend to process the retry request and regenerate content.

```json
[
  {
    "type": "chat",
    "event": "retry",
    "accountId": "hlSXkGN5z6CxsSA48IYj",
    "formId": "OuIlLGMQCcBtwkwbZmKn",
    "reviewId": "lBkTFbmXN2YfA1tCMYHm",
    "fieldId": "postDraft",
    "createdAt": "2025-08-12T22:27:39.051Z",
    "messages": [
      {
        "role": "human",
        "content": "You will be passed a scraped article from a company blog. I'm a fan of their product and will write a LinkedIn post for every news that is coming out. Please write an engaging post based on the article."
      }
    ],
    "gthLinkToReview": "https://app.gotohuman.com/accounts/hlSXkGN5z6CxsSA48IYj/reviews/lBkTFbmXN2YfA1tCMYHm"
  }
]
```

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

### Configure Selectable Options and Defaults (JS/TS SDK)

Source: https://docs.gotohuman.com/send-requests

Illustrates setting up options and a default value for form fields using the JavaScript/TypeScript SDK. This enables dynamic or fixed choices for user input.

```javascript
review.addFieldData("buttons", {
    "options": [
        {
            "id": "choice1",
            "label": "Choice 1"
        },
        {
            "id": "choice2",
            "label": "Choice 2"
        }
    ],
    "default": "choice2"
  })
```

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

### Create and Send Review Request (Python)

Source: https://docs.gotohuman.com/send-requests

This Python snippet demonstrates how to create a review request, add data to specific fields like a URL link and a text component, and then send the request. It includes error handling for the request sending process.

```Python
review = gotoHuman.create_review("abcdef12345")  
review.add_field_data("linkedin", {  
    "label": "Rodrigo G.",  
    "url": "https://www.linkedin.com/in/rodrigog12/"  
    })  
review.add_field_data("aiDraft", "Hey there, I saw...")  
try:  
    response = review.send_request()  
    print("Review sent successfully:", response)  
except Exception as e:  
    print("An error occurred:", e)
```

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

### CDN Image/Video URLs

Source: https://docs.gotohuman.com/send-requests

Details on how GoToHuman stores uploaded images and videos and provides CDN URLs in the response.

```APIDOC
## Media Storage and CDN

### Description
When review requests include images or videos, GoToHuman automatically stores these files and makes them accessible via a CDN. This ensures persistent access to media content.

### Response Example (Success Response)
```json
{
  "responseValues": {
    "imageOptions": {
      "selected": [
        "https://cdn1.gotohuman.com/..."
      ],
      "value": [
        {
          "originalUrl": "https://files.oaiusercontent.com/file-somethingsomething?se=xyz",
          "url": "https://cdn1.gotohuman.com/...",
          "response": null
        },
        {
          "response": "approved",
          "originalUrl": "https://files.oaiusercontent.com/file-somethingelse?se=xyz",
          "url": "https://cdn1.gotohuman.com/..."
        }
      ]
    },
    ...
  },
  ...
}
```

### Notes
The `selected` and `response` attributes in `imageOptions` are present only if the images field is configured as 'selectable'.
```

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

### Create Review Request using cURL

Source: https://context7.com/context7/gotohuman/llms.txt

Send a POST request to the /requestReview API endpoint to create a human review request. Requires API key, form ID, field data, metadata, assignment, and an optional webhook URL. Returns the review ID and a link to the review.

```bash
curl -X POST https://api.gotohuman.com/requestReview \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "formId": "abcdef12345",
    "fields": {
      "linkedin": {
        "label": "Rodrigo G.",
        "url": "https://www.linkedin.com/in/rodrigog12/"
      },
      "aiDraft": "Hey there, I saw your latest product launch..."
    },
    "meta": {
      "threadId": "oai-thread-443289",
      "workflowRunId": "12345"
    },
    "assignTo": ["jess@acme.org"],
    "webhookUrl": "https://api.example.com/webhooks/review-completed"
  }'

# Response:
# {
#   "reviewId": "iVcn4fvRpPhAdVnZ7v0d",
#   "gthLink": "https://app.gotohuman.com/accounts/Kb6A8ZqIaJkueTA76vv5/reviews/iVcn4fvRpPhAdVnZ7v0d"
# }
```

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

### Create Review Request using JavaScript/TypeScript SDK

Source: https://context7.com/context7/gotohuman/llms.txt

Leverage the gotoHuman JavaScript/TypeScript SDK to create and send review requests. This SDK offers a fluent interface for chaining methods to add field data, metadata, and assignments before submitting the request asynchronously.

```typescript
import { GotoHuman } from 'gotohuman';

const gotoHuman = new GotoHuman(process.env.GOTOHUMAN_API_KEY);

const reviewRequest = gotoHuman.createReview('abcdef12345')
  .addFieldData('linkedin', {
    label: 'Rodrigo G.',
    url: 'https://www.linkedin.com/in/rodrigog12/'
  })
  .addFieldData('aiDraft', 'Hey there, I saw your latest model...')
  .addMetaData('threadId', 'oai-thread-443289')
  .assignToUsers(['jess@acme.org']);

try {
  const response = await reviewRequest.sendRequest();
  console.log(`Review ID: ${response.reviewId}`);
  console.log(`Review link: ${response.gthLink}`);
} catch (error) {
  console.error('Failed to send review:', error);
}
```

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

### n8n Workflow for AI Content Review with gotoHuman

Source: https://context7.com/context7/gotohuman/llms.txt

This snippet outlines a structured n8n workflow for integrating AI content generation with gotoHuman's human review process. It covers AI node output, gotoHuman node configuration for sending and waiting for reviews, and conditional handling of 'approved' or 'rejected' responses. It also includes logic for retrying AI generation and updating existing reviews.

```javascript
// n8n workflow structure:

// 1. AI Content Generation Node
//    Output: { generatedText: "...", generatedImage: "https://..." }

// 2. gotoHuman Node (Send and Wait)
//    - Select review template from dropdown
//    - Map fields from previous node:
//      textField: {{ $json.generatedText }}
//      imageField: {{ [{url: $json.generatedImage, label: "AI Generated"}] }}
//    - Assign to: All Users
//    - This node pauses and waits for review completion

// 3. IF Node (handle response)
//    Condition: {{ $json.response }} equals "approved"

// 4a. Approved Path
//     - Access reviewed values: {{ $json.responseValues.textField.value }}
//     - Check if edited: {{ $json.responseValues.textField.wasEdited }}
//     - Publish or continue workflow

// 4b. Rejected Path
//     - Log rejection
//     - Send notification
//     - End workflow

// For AI retries, add:
// 5. Switch Node with condition: {{ $json.type }} equals "chat"
// 6. Retry Path: Re-run AI generation with new prompt: {{ $json.messages[0].content }}
// 7. Update gotoHuman Node with: Update for Review ID = {{ $json.reviewId }}

```

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

### Configuring Dynamic Options and Default for n8n Fields

Source: https://docs.gotohuman.com/Integrations/n8n

Demonstrates how to set up dynamic options and a default value for fields in n8n that correspond to user input types like checkboxes, dropdowns, or buttons in gotoHuman. This allows for flexible user choices during the review process.

```javascript
// Expression:  
{{				  			{  					options: [  					  {  						id: "choice1",  					  label: "Pick One"  					},  					  {  						id: "choice2",  					  label: "Pick Two"  					}  					],  					default: "choice2"  				  			}				}}


```

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

### API Response with Review Link

Source: https://docs.gotohuman.com/send-requests

This is a sample API response from GoToHuman, indicating a successful review request. It includes a unique `reviewId` and a direct `gthLink` to the pending review.

```json
{
    "reviewId": "iVcn4fvRpPhAdVnZ7v0d",
    "gthLink": "https://app.gotohuman.com/accounts/Kb6A8ZqIaJkueTA76vv5/reviews/iVcn4fvRpPhAdVnZ7v0d"
}
```

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

### Fetch Human Reviews

Source: https://docs.gotohuman.com/training-data

Retrieve human review data, including suggested and approved values, from the GoToHuman API. This endpoint allows filtering and grouping of responses to tailor the dataset for LLM training and prompt engineering.

```APIDOC
## GET /queryResponses

### Description
Fetches review data based on specified form and field IDs. Supports filtering by review status and grouping responses by field or review. Useful for in-context learning and training LLM agents.

### Method
GET

### Endpoint
https://api.gotohuman.com/queryResponses

### Parameters
#### Query Parameters
- **formId** (string) - Required - The ID of the review template / form.
- **fieldIds** (string) - Required - The comma-separated IDs of the fields you are interested in.
- **filterResponse** (string) - Optional - Filter by review status. Possible values: `approved`, `rejected`.
- **groupByField** (boolean) - Optional - Whether to group the responses by field. Defaults to `false` (groups by review).
- **approvedValuesOnly** (boolean) - Optional - Lists only the response values for approved reviews. Defaults to `false`.
- **rejectedValuesOnly** (boolean) - Optional - Lists only the request values for rejected reviews. Defaults to `false`.
- **limit** (number) - Optional - The number of responses to return. Defaults to `20`. Max: `500` (free plan: `20`).

### Request Example
```
https://api.gotohuman.com/queryResponses?formId=FORM_ID&fieldIds=FIELD_ID1,FIELD_ID2&filterResponse=approved
```

### Response
#### Success Response (200)
- **Response Body Structure**: Varies based on `groupByField` and `approvedValuesOnly`/`rejectedValuesOnly` parameters.

  **Case 1: `groupByField=false`**
  ```json
  [
    {
      "reviewId": "abc123456",
      "createdAt": "2025-03-12T22:25:42.415Z",
      "respondedAt": "2025-03-12T22:26:15.253Z",
      "response": "approved",
      "fields": {
        "yourFieldId1": {
          "suggestedValue": "...",
          "approvedValue": "..."
        },
        "yourFieldId2": {
          "suggestedValue": "...",
          "approvedValue": "..."
        }
      }
    }
  ]
  ```

  **Case 2: `groupByField=true`**
  ```json
  {
    "yourFieldId1": [
      {
        "reviewId": "abc123456",
        "createdAt": "2025-03-12T22:25:42.415Z",
        "respondedAt": "2025-03-12T22:26:15.253Z",
        "response": "approved",
        "suggestedValue": "...",
        "approvedValue": "..."
      }
    ]
  }
  ```

  **Case 3: `approvedValuesOnly=true` and `groupByField=false`**
  ```json
  [
    {
      "yourFieldId1": "...",
      "yourFieldId2": "..."
    }
  ]
  ```

  **Case 4: `approvedValuesOnly=true` and `groupByField=true`**
  ```json
  {
    "yourFieldId1": [
      "..."
    ],
    "yourFieldId2": [
      "..."
    ]
  }
  ```

### Authentication
Requires an `x-api-key` header with your API key.
```
x-api-key: YOUR_API_KEY
```
```

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

### Create and Send Review Request (JavaScript/TypeScript)

Source: https://docs.gotohuman.com/send-requests

This JavaScript/TypeScript snippet shows how to construct a review request using a fluent API. It chains methods to create the review, add field data for a URL link and a text component, and send the request asynchronously.

```JavaScript
const reviewRequest = gotoHuman.createReview("abcdef12345")  
    .addFieldData("linkedin", {  
        label: "Rodrigo G.",  
        url: "https://www.linkedin.com/in/rodrigog12/"  
    })  
    .addFieldData("aiDraft", "Hey there, I saw...")  
await reviewRequest.sendRequest()
```

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

### AI Retries with Prompt Editing in Python

Source: https://context7.com/context7/gotohuman/llms.txt

This Python snippet shows how to integrate AI content generation with prompt editing capabilities using the `gotohuman` library. It covers creating an initial review request with a prompt, handling webhook data for retries, and regenerating content with updated prompts to update the review.

```python
from gotohuman import GotoHuman

gotoHuman = GotoHuman()

# Initial review request with prompt
review = gotoHuman.create_review("form123")
review.add_field_data("blog", {
    "ai": {"prompt": "Write a blog post about AI automation..."},
    "content": "AI automation is transforming..."
})
response = review.send_request()

# When webhook receives retry request (type: "chat"):
# {
#   "type": "chat",
#   "event": "retry",
#   "reviewId": "lBkTFbmXN2YfA1tCMYHm",
#   "fieldId": "blog",
#   "messages": [
#     {"role": "human", "content": "Make it more engaging and shorter"}
#   ]
# }

# Regenerate content with updated prompt and update review
# edited_prompt = webhook_data['messages'][0]['content']
# new_content = generate_with_llm(edited_prompt)

# update_review = gotoHuman.create_review("form123")
# update_review.update_for_review("lBkTFbmXN2YfA1tCMYHm")
# update_review.add_field_data("blog", new_content)
# update_review.send_request()
```
Tokens:
Raw