Skip to main content

​
Introduction

The Hunch Tools API allows you to programmatically run tools and retrieve their results. This enables you to integrate Hunch’s powerful AI capabilities into your own applications, scripts, or workflows. Whether you’re building a custom integration or automating repetitive tasks, the Tools API provides a flexible way to leverage Hunch’s functionality.

​
Generating an API Key

Before you can use the Tools API, you’ll need to generate an API key:
  1. Log in to your Hunch account
  2. Click on your avatar in the upper left corner
  3. Select “API Key” section
  4. Click “Generate API Key”
  5. Copy and securely store your new API key
Important: Keep your API key confidential. It provides access to your Hunch account and should be treated like a password.

​
Finding a Tool UID

Each tool in Hunch has a unique identifier (UID). You’ll need this UID to run a specific tool via the API. To find a tool’s UID:
  1. Open the tool in the Hunch interface
  2. Look at the URL in your browser
  3. The tool UID is the first alphanumeric string after /tool/ in the URL
For example, in the URL https://app.hunch.tools/app/tool/4p2QJ/NZmZN, the tool UID is 4p2QJ.

​
Making API Requests

The Tools API has two main endpoints:
  • POST /v1beta2/tool/start-run: Starts a new run of a tool
  • GET /v1beta2/tool/run-status/{tool_run_uid}: Checks the status of a tool run
All API requests should include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Example: Starting a Tool Run

curl --request POST \
  --url https://api.hunch.tools/v1beta2/tool/start-run \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "tool_uid": "4p2QJ",
  "inputs": [
    {"title": "Name", "text": "Bob"}
  ]
}'
This request will return a JSON object containing the tool_run_uid, which you’ll use to check the run status.

​
Example: Checking Tool Run Status

curl --request GET \
  --url https://api.hunch.tools/v1beta2/tool/run-status/TOOL_RUN_UID \
  --header 'Authorization: Bearer YOUR_API_KEY'
The response will include the run status (RUNNING, COMPLETED, or FAILED) and, if completed, the outputs of the tool.

​
Workflow Integration

Hunch tools can be easily integrated into popular workflow automation platforms like Zapier and Make.com (formerly Integromat). These platforms allow you to create complex workflows that can trigger Hunch tools based on various events or schedules, and then use the results in subsequent steps of your workflow.

​
Best Practices

  1. Rate Limiting: Be mindful of AI provider rate limits.
  2. Secure Storage: Always store your API key securely and never expose it in client-side code.
  3. Asynchronous Processing: For tools that may take longer to run, implement asynchronous processing by starting the run and then periodically checking its status.
  4. Error Handling: Implement robust error handling to manage potential API errors or unexpected responses.

​
Next Steps

  • Explore the full API documentation for detailed information on request and response structures.
  • Experiment with different tools to see how they can enhance your workflows and applications.
  • Join our community Discord to share your integrations and get help from other developers.
By leveraging the Tools API, you can unlock the full potential of Hunch’s AI capabilities in your own projects and workflows. Happy building!

​
Bonus: Complete Python Example

Here’s a complete Python script that starts a tool run and waits for it to complete:
Python
import requests
import time
import os


url = "https://api.hunch.tools/v1beta2/tool/start-run"
api_key = os.getenv("HUNCH_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}

data = {
    "tool_uid": "4p2QJ",
    "inputs": [
        {"title": "Name", "text": "Bob"}
    ]
}

response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
tool_run_uid = response.json()["tool_run_uid"]

url = f"https://api.hunch.tools/v1beta2/tool/run/{tool_run_uid}"

while True:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    data = response.json()
    if data["status"] == "COMPLETED":
        break
    time.sleep(5)

for output in data["outputs"]:
    print(f"{output['title']}:\n{output['text']}\n")