HookQ API

export HOOKQ_API_KEY="hq_live_your_key_here"
export HOOKQ_BASE_URL="http://localhost:3000"   # replace with your host

curl -sS "$HOOKQ_BASE_URL/api/v1/tools" \
  -H "Authorization: Bearer $HOOKQ_API_KEY"

curl -sS -X POST "$HOOKQ_BASE_URL/api/v1/run" \
  -H "Authorization: Bearer $HOOKQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gmail","action":"gmail_get_profile","input":{}}'

{
  "ok": true,
  "result": {
    "emailAddress": "you@example.com",
    "messagesTotal": 42,
    "threadsTotal": 30,
    "historyId": "12345"
  }
}

Authorization: Bearer hq_live_your_key_here

curl -sS "$HOOKQ_BASE_URL/api/v1/integrations" \
  -H "Authorization: Bearer $HOOKQ_API_KEY"

{
  "integrations": [
    {
      "provider": "gmail",
      "name": "Gmail",
      "status": "connected",
      "scopes": ["https://www.googleapis.com/auth/gmail.modify"],
      "tools": 3,
      "connectedAt": "2026-10-11T09:00:00.000Z"
    }
  ]
}

# All tools
curl -sS "$HOOKQ_BASE_URL/api/v1/tools" \
  -H "Authorization: Bearer $HOOKQ_API_KEY"

# Just Gmail tools
curl -sS "$HOOKQ_BASE_URL/api/v1/tools?provider=gmail" \
  -H "Authorization: Bearer $HOOKQ_API_KEY"

{
  "tools": [
    {
      "provider": "gmail",
      "name": "gmail_list_messages",
      "description": "List recent Gmail messages with sender, subject, date, and snippet. Supports a Gmail search query such as 'is:unread from:alice@acme.com'.",
      "write": false,
      "connected": true,
      "constraints": {},
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Gmail search query (optional)"
          },
          "max": {
            "type": "string",
            "description": "Max results (1–25, default 10)"
          }
        },
        "required": [],
        "additionalProperties": false
      }
    }
  ]
}

curl -sS -X POST "$HOOKQ_BASE_URL/api/v1/run" \
  -H "Authorization: Bearer $HOOKQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gmail",
    "action": "gmail_list_messages",
    "input": { "query": "is:unread", "max": "5" }
  }'

curl -sS -X POST "$HOOKQ_BASE_URL/api/v1/run" \
  -H "Authorization: Bearer $HOOKQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gmail",
    "action": "gmail_send_email",
    "input": {
      "to": "someone@example.com",
      "subject": "Hello from HookQ",
      "body": "Sent by my agent."
    },
    "confirm": true
  }'

{ "ok": true, "result": { "ok": true, "id": "1920abc...", "threadId": "1920abc..." } }

const BASE_URL = process.env.HOOKQ_BASE_URL ?? "http://localhost:3000";
const API_KEY = process.env.HOOKQ_API_KEY;
if (!API_KEY) throw new Error("Set HOOKQ_API_KEY first");

async function run(provider, action, input = {}, confirm = false) {
  const res = await fetch(`${BASE_URL}/api/v1/run`, {
    method: "POST",
    signal: AbortSignal.timeout(30_000),
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ provider, action, input, confirm }),
  });
  const data = await res.json().catch(() => {
    throw new Error(`HTTP ${res.status}: non-JSON response`);
  });
  if (!res.ok) throw new Error(`${data.error?.code ?? res.status}: ${data.error?.message ?? res.statusText}`);
  return data.result;
}

// List unread Gmail messages
const messages = await run("gmail", "gmail_list_messages", { query: "is:unread", max: "5" });
console.log(messages);

import os
import requests

BASE_URL = os.environ.get("HOOKQ_BASE_URL", "http://localhost:3000")
API_KEY = os.environ["HOOKQ_API_KEY"]

def run(provider, action, input=None, confirm=False):
    payload = {"provider": provider, "action": action, "input": input or {}}
    payload["confirm"] = confirm
    res = requests.post(
        f"{BASE_URL}/api/v1/run",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=30,
    )
    try:
        data = res.json()
    except ValueError:
        raise RuntimeError(f"HTTP {res.status_code}: non-JSON response") from None
    if not res.ok:
        error = data.get("error", {})
        raise RuntimeError(f"{error.get('code', res.status_code)}: {error.get('message', res.reason)}")
    return data["result"]

# List your GitHub repos
repos = run("github", "github_list_repos", {"max": "5"})
print(repos)

curl -sS -X POST "$HOOKQ_BASE_URL/api/mcp" \
  -H "Authorization: Bearer $HOOKQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

{
  "mcpServers": {
    "hookq": {
      "url": "https://your-hookq-host/api/mcp",
      "headers": { "Authorization": "Bearer hq_live_your_key_here" }
    }
  }
}

HOOKQ_API_KEY=hq_live_your_key_here \
HOOKQ_BASE_URL=http://localhost:3000 \
npm run --silent mcp

{
  "mcpServers": {
    "hookq": {
      "command": "npm",
      "args": ["--prefix", "/absolute/path/to/connectQ", "run", "--silent", "mcp"],
      "env": {
        "HOOKQ_API_KEY": "hq_live_your_key_here",
        "HOOKQ_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes model

mcp_servers:
  hookq:
    url: "http://localhost:3000/api/mcp"
    headers:
      Authorization: "Bearer hq_live_your_key_here"
    timeout: 60

hermes mcp test hookq   # should list the three HookQ tools
hermes                     # start a chat

List my connected HookQ apps, then show my 5 most recent unread Gmail messages.

mkdir grok-hookq && cd grok-hookq
python3 -m venv .venv && source .venv/bin/activate
python -m pip install openai requests

export XAI_API_KEY="xai-your_key_here"
export HOOKQ_API_KEY="hq_live_your_key_here"
# Optional: export GROK_MODEL="grok-4.7"

export HOOKQ_MCP_URL="https://your-hookq-host/api/mcp"

import os
import sys

from openai import OpenAI

grok = OpenAI(api_key=os.environ["XAI_API_KEY"], base_url="https://api.x.ai/v1")
prompt = " ".join(sys.argv[1:]) or "List my connected HookQ apps."

response = grok.responses.create(
    model=os.environ.get("GROK_MODEL", "grok-4.7"),
    input=[{"role": "user", "content": prompt}],
    tools=[{
        "type": "mcp",
        "server_url": os.environ["HOOKQ_MCP_URL"],
        "server_label": "hookq",
        "authorization": os.environ["HOOKQ_API_KEY"],
    }],
)
print(response.output_text)

python grok_mcp.py "List my connected HookQ apps, then get my Gmail profile."

export HOOKQ_BASE_URL="http://localhost:3000"

import json
import os

import requests
from openai import OpenAI

HOOKQ_BASE_URL = os.environ.get("HOOKQ_BASE_URL", "http://localhost:3000").rstrip("/")
HOOKQ_HEADERS = {"Authorization": f"Bearer {os.environ['HOOKQ_API_KEY']}"}
MODEL = os.environ.get("GROK_MODEL", "grok-4.7")
MAX_TOOL_ROUNDS = 10

grok = OpenAI(api_key=os.environ["XAI_API_KEY"], base_url="https://api.x.ai/v1")


def hookq(method, path, **kwargs):
    res = requests.request(method, f"{HOOKQ_BASE_URL}{path}", headers=HOOKQ_HEADERS, timeout=30, **kwargs)
    try:
        return res.status_code, res.json()
    except ValueError:
        return res.status_code, {"error": {"code": str(res.status_code), "message": "non-JSON response"}}


# 1. Discover the tools this key may use, keeping only connected apps.
status, data = hookq("GET", "/api/v1/tools")
if status != 200:
    raise SystemExit(f"Tool discovery failed ({status}): {data}")
catalog = {t["name"]: t for t in data["tools"] if t["connected"]}
if not catalog:
    raise SystemExit("No connected tools. Connect an app and select its actions on your API key.")

# 2. Expose each HookQ tool to Grok as a function.
tools = [
    {
        "type": "function",
        "name": t["name"],
        "description": ("[WRITE - asks the user first] " if t["write"] else "") + t["description"],
        "parameters": t["inputSchema"],
    }
    for t in catalog.values()
]


# 3. Execute a function call through HookQ. Writes need a "y" from you.
def run_tool(name, arguments):
    tool = catalog.get(name)
    if tool is None:
        return {"error": {"code": "unknown_action", "message": f"No tool named {name}"}}
    try:
        args = json.loads(arguments or "{}")
    except json.JSONDecodeError:
        return {"error": {"code": "invalid_arguments", "message": "Arguments were not valid JSON"}}
    args = {key: str(value) for key, value in args.items()}  # HookQ inputs are strings

    confirm = False
    if tool["write"]:
        print(f"\nGrok wants to run {name} ({tool['provider']}) with:\n{json.dumps(args, indent=2)}")
        if input("Allow this write? [y/N] ").strip().lower() != "y":
            return {"error": {"code": "user_declined", "message": "The user declined this action."}}
        confirm = True

    _, result = hookq("POST", "/api/v1/run", json={
        "provider": tool["provider"], "action": name, "input": args, "confirm": confirm,
    })
    return result


# 4. Agent loop: let Grok call tools until it answers in text.
def ask(prompt, previous_id=None):
    response = grok.responses.create(
        model=MODEL, tools=tools, previous_response_id=previous_id,
        input=[{"role": "user", "content": prompt}],
    )
    for _ in range(MAX_TOOL_ROUNDS):
        calls = [item for item in response.output if item.type == "function_call"]
        if not calls:
            return response
        outputs = [
            {"type": "function_call_output", "call_id": call.call_id,
             "output": json.dumps(run_tool(call.name, call.arguments))}
            for call in calls
        ]
        response = grok.responses.create(
            model=MODEL, tools=tools, previous_response_id=response.id, input=outputs,
        )
    raise RuntimeError(f"Stopped after {MAX_TOOL_ROUNDS} tool rounds")


print(f"Grok + HookQ ready with {len(tools)} tools. Ctrl+C to quit.")
last_id = None
while True:
    prompt = input("\nYou: ").strip()
    if not prompt:
        continue
    response = ask(prompt, last_id)
    last_id = response.id
    print(f"\nGrok: {response.output_text}")

python grok_agent.py

Grok + HookQ ready with 3 tools. Ctrl+C to quit.

You: Summarize my 5 most recent unread emails.