# GET & PATCH /api/actions/[id]
Source: https://docs.openhermit.com/api/actions

Read or update an action's configuration and agent prompts.

## GET — fetch an action

```bash theme={null}
GET https://openhermit.com/api/actions/{action_id}
```

Returns the full action record including all configured prompts.

### Response

```json theme={null}
{
  "action": {
    "id": "uuid",
    "name": "Contact Form",
    "type": "contact_form",
    "tool_name": "contact_form",
    "tool_description": "Send a message to the team",
    "selector": "#contact-form",
    "page_url": "https://example.com/contact",
    "enabled": true,
    "before_prompt": "Have name and email ready.",
    "success_prompt": "Form submitted. We reply within 24h.",
    "failure_prompt": "Try hello@example.com directly.",
    "next_action_url": "https://calendly.com/example/30min",
    "next_action_label": "Book a meeting",
    "created_at": "2025-01-15T10:30:00Z"
  }
}
```

***

## PATCH — update an action

```bash theme={null}
PATCH https://openhermit.com/api/actions/{action_id}
Content-Type: application/json
```

Update any combination of the following fields:

```json theme={null}
{
  "enabled": true,
  "tool_description": "Updated description for agents",
  "before_prompt": "Updated before prompt",
  "success_prompt": "Updated success prompt",
  "failure_prompt": "Updated failure prompt",
  "next_action_url": "https://calendly.com/example/30min",
  "next_action_label": "Book a meeting"
}
```

| Field               | Type           | Description                       |
| ------------------- | -------------- | --------------------------------- |
| `enabled`           | boolean        | Show/hide this action from agents |
| `tool_description`  | string         | How agents understand this action |
| `before_prompt`     | string \| null | Shown to agent before acting      |
| `success_prompt`    | string \| null | Returned after success            |
| `failure_prompt`    | string \| null | Returned after failure            |
| `next_action_url`   | string \| null | URL to chain agents to next       |
| `next_action_label` | string \| null | Label for the next action         |

### Response

```json theme={null}
{
  "success": true,
  "action": { "...updated fields..." }
}
```

### Authentication

Both endpoints require the user to be authenticated via Supabase session cookie. They are dashboard-facing — not designed for cross-origin use.


# POST /api/events
Source: https://docs.openhermit.com/api/events

Track an agent interaction event on an action.

Called by `script.js` when an agent submits a form or when a page view is detected from a known AI user-agent. Also callable directly from your own code.

## Request

```bash theme={null}
POST https://openhermit.com/api/events
Content-Type: application/json
```

```json theme={null}
{
  "api_key": "YOUR_API_KEY",
  "event_type": "completion",
  "action_tool_name": "contact_form",
  "agent_name": "Claude",
  "page_url": "https://yoursite.com/contact"
}
```

| Field              | Type   | Required | Description                                      |
| ------------------ | ------ | -------- | ------------------------------------------------ |
| `api_key`          | string | Yes      | Your website's API key                           |
| `event_type`       | string | Yes      | `view`, `completion`, or `error`                 |
| `action_tool_name` | string | No       | The `tool_name` of the action being tracked      |
| `agent_name`       | string | No       | Name of the AI agent (from user-agent detection) |
| `page_url`         | string | No       | URL of the page the event occurred on            |

## Event types

| Type         | When it's sent                    |
| ------------ | --------------------------------- |
| `view`       | An AI agent is detected on a page |
| `completion` | A form is successfully submitted  |
| `error`      | A form submission fails           |

## Response

```json theme={null}
{
  "success": true,
  "agent_prompt": "Form submitted. Our team responds within 24 hours.",
  "next_actions": [
    {
      "url": "https://calendly.com/example/30min",
      "label": "Book a meeting"
    }
  ]
}
```

The response includes any configured `success_prompt` (on completion) or `failure_prompt` (on error) so your code can forward it to the agent.

## CORS

Accepts cross-origin requests (`Access-Control-Allow-Origin: *`).


# GET /api/manifest
Source: https://docs.openhermit.com/api/manifest

Retrieve the WebMCP manifest for a website.

Returns the full WebMCP-compliant JSON manifest for a website. This is the data AI agents read to understand your site's available actions.

## Request

```bash theme={null}
GET https://openhermit.com/api/manifest?key=YOUR_API_KEY
```

Or via the canonical WebMCP path (recommended — works via a rewrite):

```bash theme={null}
GET https://yoursite.com/.well-known/webmcp.json
```

## Response

```json theme={null}
{
  "webmcp_version": "1.0",
  "site": {
    "name": "Acme Corp",
    "domain": "acme.com",
    "description": "We build great products.",
    "agent_instructions": "This site has 2 agent-ready actions: contact_form and book_consultation."
  },
  "actions": [
    {
      "name": "Contact Form",
      "type": "contact_form",
      "tool_name": "contact_form",
      "description": "Send a message to the Acme team",
      "selector": "#contact-form",
      "page_url": "https://acme.com/contact",
      "enabled": true,
      "before_prompt": "Have name, email and question ready.",
      "success_prompt": "Message sent. We reply within 24 hours.",
      "failure_prompt": "Email hello@acme.com directly.",
      "next_action": {
        "url": "https://calendly.com/acme/30min",
        "label": "Book a meeting"
      },
      "fields": [
        { "name": "name", "type": "text", "required": true },
        { "name": "email", "type": "email", "required": true },
        { "name": "message", "type": "textarea", "required": false }
      ]
    }
  ]
}
```

## Notes

* Only **enabled** actions are included. Disabled actions are omitted entirely.
* The `/.well-known/webmcp.json` path is handled via a Next.js rewrite — no separate file is needed on your server.
* Response includes `X-WebMCP: enabled` and `X-OpenHermit: 1.0` headers.
* This endpoint is public — no authentication required (the API key is in the query string, identifying which site to return).

## CORS

Accepts cross-origin requests (`Access-Control-Allow-Origin: *`).


# POST /api/ping
Source: https://docs.openhermit.com/api/ping

Confirm script installation and update last_ping_at timestamp.

Called automatically by `script.js` on every page load. Updates the `last_ping_at` timestamp on the website, which drives the installation badge in the dashboard.

## Request

```bash theme={null}
POST https://openhermit.com/api/ping
Content-Type: application/json
```

```json theme={null}
{
  "api_key": "YOUR_API_KEY",
  "page_url": "https://yoursite.com/contact",
  "script_version": "1.0.0"
}
```

| Field            | Type   | Required | Description                              |
| ---------------- | ------ | -------- | ---------------------------------------- |
| `api_key`        | string | Yes      | Your website's API key                   |
| `page_url`       | string | No       | The URL of the page the script loaded on |
| `script_version` | string | No       | Version of the script running            |

## Response

```json theme={null}
{
  "ok": true,
  "page_url": "https://yoursite.com/contact"
}
```

## CORS

This endpoint accepts cross-origin requests (`Access-Control-Allow-Origin: *`). It is designed to be called from any domain by the client script.


# POST /api/actions/sync
Source: https://docs.openhermit.com/api/sync

Sync detected actions from a page and receive configured agent prompts.

Called by `script.js` after scanning a page. Upserts detected actions into the database and returns any agent prompts you've configured — which the script then injects into the page DOM.

## Request

```bash theme={null}
POST https://openhermit.com/api/actions/sync
Content-Type: application/json
```

```json theme={null}
{
  "api_key": "YOUR_API_KEY",
  "page_url": "https://yoursite.com/contact",
  "page_title": "Contact Us",
  "actions": [
    {
      "type": "contact_form",
      "name": "Contact Form",
      "tool_name": "contact_form",
      "tool_description": "Send a message to the team via the contact form",
      "selector": "#contact-form",
      "fields": [
        { "name": "name", "type": "text", "required": true },
        { "name": "email", "type": "email", "required": true },
        { "name": "message", "type": "textarea", "required": false }
      ]
    }
  ]
}
```

## Response

```json theme={null}
{
  "success": true,
  "actions": [
    {
      "id": "uuid",
      "tool_name": "contact_form",
      "selector": "#contact-form",
      "before_prompt": "Please have name and email ready.",
      "success_prompt": "Form submitted. We reply within 24h.",
      "failure_prompt": "Try hello@example.com directly.",
      "next_action_url": "https://calendly.com/example/30min",
      "next_action_label": "Book a meeting"
    }
  ]
}
```

## Behaviour

* If an action with the same `tool_name` already exists for this website, it is **updated** (name, type, selector, description) — existing prompt configuration is **preserved**.
* If the action is new, it is **created** with no prompts (configure them in the dashboard).
* Sending an empty `actions` array is valid — it confirms the script is running on a page without forms.

## CORS

Accepts cross-origin requests (`Access-Control-Allow-Origin: *`).


# Agent Prompts
Source: https://docs.openhermit.com/guides/agent-prompts

Control exactly what AI agents do before, during, and after each action.

Agent prompts are the most powerful feature in OpenHermit. They let you guide AI agents through your actions — providing context before they act, confirming success, handling failures, and chaining to next steps.

## The three prompts

Navigate to **Actions → Edit Prompts** for any detected action.

### Before Prompt

Shown to the agent *before* it attempts the action. Use this to tell the agent what information it needs to collect from the user first.

```
Before Prompt example:
"Please confirm you have the customer's full name, email address, 
and a clear description of their question before submitting this form."
```

**When to use it:**

* Your form requires specific data the agent might not have ready
* You want to prevent incomplete or low-quality submissions
* You need the agent to set expectations with the user before proceeding

***

### Success Prompt

Returned to the agent after the action completes successfully. Use this to confirm what happens next and guide the agent's response to the user.

```
Success Prompt example:
"The contact form was submitted successfully. Our team responds 
within 24 business hours. If this is urgent, the customer can also 
book a direct meeting at calendly.com/yourname/30min"
```

**When to use it:**

* Tell agents realistic response timeframes
* Offer alternative contact methods for urgent cases
* Chain to the next best action (booking, payment, etc.)

***

### Failure Prompt

Returned if the action fails (form validation error, network issue, etc.). Prevents agents from leaving users stuck.

```
Failure Prompt example:
"The form could not be submitted. Please ask the customer to try 
again, or offer them our direct email: hello@example.com or 
phone: +41 44 123 4567"
```

***

### Next Action URL + Label

After a successful action, you can chain agents directly to the next step. This appears in the manifest and gets injected as a suggested next action.

| Field             | Example                               |
| ----------------- | ------------------------------------- |
| Next Action URL   | `https://calendly.com/yourname/30min` |
| Next Action Label | `Book a 30-minute meeting`            |

***

## How prompts reach agents

Prompts are delivered in two ways simultaneously:

**1. Via the manifest** (`/.well-known/webmcp.json`)

```json theme={null}
{
  "actions": [
    {
      "name": "contact_form",
      "tool_name": "contact_form",
      "before_prompt": "Please have name and email ready...",
      "success_prompt": "Form submitted. We reply within 24h...",
      "failure_prompt": "Try our direct email...",
      "next_action": {
        "url": "https://calendly.com/...",
        "label": "Book a meeting"
      }
    }
  ]
}
```

**2. Injected into the page DOM**

The script adds a hidden element to each page with your prompts, so agents reading the live DOM can also see them:

```html theme={null}
<div 
  aria-label="WebMCP Agent Instructions" 
  style="position:absolute;left:-9999px;"
>
  Before: Please have name and email ready...
  Success: Form submitted. We reply within 24h...
</div>
```

***

## Prompt writing tips

<AccordionGroup>
  <Accordion title="Be specific about timing">
    Bad: "We will respond soon."\
    Good: "Our team responds within 24 business hours Monday–Friday. Weekend submissions are handled on Monday."
  </Accordion>

  <Accordion title="Always provide a fallback">
    Bad: "If this fails, try again."\
    Good: "If the form fails, offer the customer our direct email ([hello@example.com](mailto:hello@example.com)) or phone (+41 44 123 4567)."
  </Accordion>

  <Accordion title="Use the success prompt for upselling">
    After a contact form: "We also offer a free 15-minute consultation — suggest booking at calendly.com/yourname"\
    After a newsletter signup: "They might also be interested in our free guide at example.com/guide"
  </Accordion>

  <Accordion title="Keep before prompts short">
    Agents read before prompts before acting. Long prompts slow the interaction. Keep them to 1–2 sentences with the essential requirement.
  </Accordion>
</AccordionGroup>


# Dashboard Guide
Source: https://docs.openhermit.com/guides/dashboard

A walkthrough of every section in the OpenHermit dashboard.

## Overview

The dashboard is your central hub for managing websites, viewing detected actions, configuring agent prompts, and monitoring analytics. Access it at [openhermit.com/dashboard](https://openhermit.com/dashboard).

***

## Overview page

The first page you see after logging in. Shows:

* **Welcome message** with your name
* **Stats row** — total websites, actions, interactions, and active agents
* **Quick actions** — shortcuts to Add Website, View Analytics, and Manage Actions
* **Getting Started stepper** — three steps (Add Website → Auto Detect → Track & Optimize)

***

## Websites

**`/dashboard/websites`**

Lists all your registered websites. For each website you can see:

* Name and domain
* Status badge (active / inactive)
* Script installation status (green dot = script detected, amber = not yet detected)
* Number of detected actions
* Number of agent interactions
* API key (truncated, with copy button)

Click **View →** to open the website detail page.

***

## Website detail

**`/dashboard/websites/[id]`**

The most important page per website. Contains:

### Installation status badge

Shows whether the script is correctly installed and when it was last seen. Updates automatically every 15 seconds — no manual refresh needed.

| Status                              | Meaning                                |
| ----------------------------------- | -------------------------------------- |
| 🟡 Script not yet detected          | Script has never pinged from this site |
| 🟢 Script active · Last seen 3m ago | Working correctly                      |
| ⚪ Script detected (inactive)        | Not seen in the last 24 hours          |

### Stats row

* **Actions** — how many forms/widgets have been detected
* **Interactions** — total agent events recorded
* **Completions** — successful form submissions by agents
* **Conv. Rate** — completions ÷ interactions

### API Key

Your site's unique API key. Used in the script tag and all API calls. Copy it here.

### Installation Script

The exact script tag to paste into your website. One-click copy.

### Details

Domain, status, date added, and a link to view your raw WebMCP manifest JSON.

### Detected Actions

All actions found on this website. Click **Edit** next to any action to configure its agent prompts.

### Recent Interactions

The last 20 agent events on this website — agent name, page URL, event type, and timestamp.

***

## Add Website

**`/dashboard/websites/new`**

Two-step flow:

**Step 1 — Enter details**

* Website name (your label, e.g. "My Portfolio")
* Domain (e.g. `example.com`)

Click **Generate Script** — this creates the website record and generates a unique API key.

**Step 2 — Install the script**
Copy the generated script tag and paste it into your website. The page shows a "What happens next" guide explaining the auto-detection flow.

***

## Actions

**`/dashboard/actions`**

All detected actions across all your websites. Stats across the top:

* Total actions detected
* Active actions (enabled)
* Total interactions
* Number of websites with actions

Each action card shows:

* Action type icon and name
* Active / Disabled badge
* Website domain and CSS selector
* WebMCP tool name and description
* Interaction count and detection date
* **Edit Prompts** button and Enable/Disable toggle

***

## Edit Action Prompts

**`/dashboard/actions/[id]`**

Configure how AI agents interact with a specific action. Three sections:

**WebMCP Identity**

* Tool name (auto-generated, read-only)
* Description — what agents read to decide whether to use this action

**Agent Prompts**

* Before prompt — shown before the agent acts
* Success prompt — returned after successful completion
* Failure prompt — returned if the action fails

**Next Step**

* Next action URL — chain agents to the next best step
* Next action label — human-readable label for the URL

See the [Agent Prompts guide](/guides/agent-prompts) for writing tips.

***

## Analytics

**`/dashboard/analytics`**

Shows the last 30 days of agent interaction data:

* **Total Interactions** — all agent events
* **Conversions** — completed actions
* **Conversion Rate** — with industry average comparison
* **Active Agents** — unique agents seen

**Agent Breakdown** — bar chart showing each agent's interaction and conversion counts.

**Recent Interactions** — last 10 events with agent name, action, website domain, event type, and timestamp.

***

## Settings

**`/dashboard/settings`**

* **Profile** — update your full name (email cannot be changed)
* **Subscription** — current plan details and upgrade option
* **API Keys** — link to the Websites section for key management
* **Danger Zone** — delete your account permanently


# Verifying Installation
Source: https://docs.openhermit.com/guides/installation-verification

How to confirm the OpenHermit script is correctly installed on your website.

## The installation badge

Every website in your dashboard shows a real-time installation status badge. It updates automatically — no refresh needed.

| Badge                                   | Meaning                                                             |
| --------------------------------------- | ------------------------------------------------------------------- |
| 🟡 **Script not yet detected**          | The script has never pinged from this website                       |
| 🟢 **Script active · Last seen 3m ago** | Script is installed and running correctly                           |
| ⚪ **Script detected (inactive)**        | Script was seen more than 24h ago — check if it's still on the page |

The badge polls every 15 seconds. After you paste the script and visit a page, it will turn green within seconds.

***

## Manual verification

If the badge stays amber, verify the script is correctly installed:

### 1. View page source

In any browser, press `Ctrl+U` (Windows) or `Cmd+U` (Mac) to view the raw HTML source. Search for `openhermit` — you should see:

```html theme={null}
<script
  src="https://openhermit.com/script.js"
  data-api-key="YOUR_KEY_HERE"
  async>
</script>
```

**Common issues:**

* The script is only on the homepage, not all pages — add it to your layout/template
* The `data-api-key` is empty or wrong — copy it again from the dashboard
* The script URL is wrong — it must be `https://openhermit.com/script.js`

### 2. Check the browser console

Open DevTools (F12) → Console. The script logs a warning if something is wrong:

```
[OpenHermit] No data-api-key found on script tag.
```

If you see no OpenHermit messages at all, the script file itself may not be loading (check the Network tab for a failed request to `script.js`).

### 3. Check network requests

In DevTools → Network tab, filter by `openhermit`. You should see:

* A request to `script.js` (status 200)
* A POST to `/api/ping` (status 200)
* A POST to `/api/actions/sync` (status 200)

***

## Forms not detected?

If the script is confirmed active but no actions appear in your dashboard:

**The form might be on a different page.** The script only detects forms on the current page. Make sure you visit the specific page containing the form — not just the homepage.

**The form might be loaded dynamically.** React, Vue, and Angular apps often render forms after the initial page load. The script has a MutationObserver that handles this, but there can be a short delay. Wait 2–3 seconds after the form appears before checking.

**The form might not look like a form.** If a "form" is built entirely with `div` and `onClick` handlers (not real `<form>` and `<input>` tags), the script can't detect it. Consider adding `data-mcp-action` attributes manually.

**Third-party widgets need special handling.** Calendly, Typeform, HubSpot etc. are detected by checking for their JavaScript objects or DOM elements. If a widget is embedded via a plain iframe with no identifying attributes, it won't be detected.

***

## Adding detection manually

For any element the script can't auto-detect, add WebMCP attributes directly in your HTML:

```html theme={null}
<div
  data-mcp-action="booking"
  data-mcp-description="Book a 30-minute strategy call with our team"
  data-mcp-params='{"name": "required", "email": "required", "message": "optional"}'
>
  <!-- your booking widget here -->
</div>
```

The script will pick up these attributes and include the action in the next sync.


# Supported AI Agents
Source: https://docs.openhermit.com/guides/supported-agents

Which AI agents OpenHermit detects and works with.

## How agent detection works

OpenHermit identifies AI agents in two ways:

1. **User-agent string** — most crawlers and agents identify themselves in the HTTP `User-Agent` header. The script checks this against known patterns.
2. **Browser heuristics** — headless browsers used by agents often expose `navigator.webdriver = true` or lack standard browser APIs.

When an agent is detected, its name is recorded with every interaction event, so you can see exactly which agents are visiting your site in the Analytics dashboard.

***

## Detected agents

| Agent             | Company       | User-agent pattern                                     |
| ----------------- | ------------- | ------------------------------------------------------ |
| GPTBot            | OpenAI        | `GPTBot`                                               |
| ChatGPT-User      | OpenAI        | `ChatGPT-User`                                         |
| OAI-SearchBot     | OpenAI        | `OAI-SearchBot`                                        |
| Operator          | OpenAI        | `openai-operator`                                      |
| Claude            | Anthropic     | `ClaudeBot`, `Claude-Web`, `Anthropic`                 |
| Perplexity        | Perplexity AI | `PerplexityBot`                                        |
| Gemini / Google   | Google        | `Google-Extended`, `Googlebot-Extended`                |
| Copilot           | Microsoft     | `bingbot.*copilot`, `copilot`                          |
| YouBot            | You.com       | `YouBot`                                               |
| Cohere            | Cohere        | `cohere-ai`                                            |
| Headless Agent    | Unknown       | `navigator.webdriver = true`, no Chrome/Safari globals |
| Automated Browser | Unknown       | `navigator.webdriver = true`                           |

***

## How agents interact with your site

### Manifest-reading agents (works today)

Any agent that can make HTTP requests can fetch your `/.well-known/webmcp.json` manifest and read your available actions, prompts, and field requirements. This works with:

* API-based agents (no browser needed)
* Curl, Python scripts, n8n automations
* Any agent framework that checks for WebMCP manifests

### Browser-based agents (works today, limited)

Agents like ChatGPT Operator, Claude Computer Use, and similar tools that control a real browser will see your WebMCP meta tags and link tags injected by the script. Forward-looking agents will follow these to discover your manifest.

### `navigator.modelContext` agents (coming soon)

The [W3C WebMCP spec](https://webmachinelearning.github.io/webmcp/) proposes a native browser API for agents. When browsers ship this natively, agents will be able to discover and call actions directly from the page without any extension. OpenHermit-enabled sites will be compatible automatically.

***

## What agents can do with your actions

Once an agent reads your manifest and finds an action, it can:

1. **Read the before prompt** — understand what data it needs to collect first
2. **Identify the form** — via `selector` (CSS selector) or `page_url`
3. **Fill the form** — using the `fields` schema to know what each field expects
4. **Submit** — and receive the success or failure prompt in response
5. **Follow the next action** — if you've configured a `next_action_url`

***

## Adding support for a new agent

If you see interactions from an agent listed as "Unknown" in your analytics, [open an issue on GitHub](https://github.com/Benjaminamos11/openhermit/issues) with the agent's user-agent string. We'll add it to the detection list in the next script release.


# Troubleshooting & FAQ
Source: https://docs.openhermit.com/guides/troubleshooting

Common issues and answers for OpenHermit users.

## Installation

<AccordionGroup>
  <Accordion title="I pasted the script but the dashboard still shows 'Script not yet detected'">
    Work through this checklist:

    **1. Check the script is actually on the page**
    Press `Ctrl+U` (Windows) or `Cmd+U` (Mac) in your browser to view the raw HTML source. Search for `openhermit` — the script tag should appear near the bottom, before `</body>`.

    **2. Check the API key is correct**
    Compare the `data-api-key` in your HTML with the key shown in your dashboard. They must match exactly.

    **3. Check the browser console**
    Open DevTools (F12) → Console. Look for any errors related to `script.js`. If you see `No data-api-key found`, the attribute is missing or misspelled.

    **4. Check for Content Security Policy (CSP) blocks**
    If your site has a strict CSP, it may block the script from loading or making requests to `openhermit.com`. You'll see a CSP error in the Console. Add `https://openhermit.com` to your `script-src` and `connect-src` directives.

    **5. Visit the page in a browser**
    The script runs in the visitor's browser — it doesn't run during server-side rendering. Open the page in a real browser (not just deploy it) and the ping will fire.
  </Accordion>

  <Accordion title="The script is detected but no actions appear">
    The script confirmed it's running (ping is working) but found no forms on that specific page.

    * **The form is on a different page.** Visit the page that actually contains the contact form, booking widget, etc. The script scans one page at a time.
    * **The form loads dynamically.** React/Vue/Angular apps render forms after the initial HTML. Wait 2–3 seconds after the form appears, then check the dashboard.
    * **The form isn't a real `<form>` element.** Some builders (Webflow, custom React components) use `div` and `onClick` instead of `<form>` and `<input>`. The script can't detect these automatically. See [Manual detection](/guides/installation-verification#adding-detection-manually).
  </Accordion>

  <Accordion title="I'm using Next.js and the script isn't detecting forms">
    In Next.js, use `strategy="afterInteractive"` — not `lazyOnload` or `beforeInteractive`:

    ```tsx theme={null}
    <Script
      src="https://openhermit.com/script.js"
      data-api-key="YOUR_KEY"
      strategy="afterInteractive"
    />
    ```

    `afterInteractive` runs after React hydration, which means the page's forms are already in the DOM when the script scans. `lazyOnload` waits too long on fast connections and can miss forms.

    Also make sure the Script component is in your **root layout** (`app/layout.tsx`), not just on one page.
  </Accordion>

  <Accordion title="The script is on my homepage but I have forms on other pages">
    The script should be on **every page** of your website — ideally added once to your global layout or template, not per-page.

    * **Next.js:** Add to `app/layout.tsx`
    * **WordPress:** Add via `functions.php` with `wp_footer` hook
    * **Webflow/Squarespace:** Use the platform's "Footer Code" setting — this adds it globally
    * **HTML sites:** Copy the script tag into every HTML file's `</body>` section
  </Accordion>
</AccordionGroup>

***

## Form detection

<AccordionGroup>
  <Accordion title="My contact form was detected but the wrong type was assigned">
    The script classifies forms by scanning the HTML for keyword signals. If your form has unusual labels or is in a non-English language, it may be misclassified.

    You can override the type by adding a `data-mcp-action` attribute to your `<form>` element:

    ```html theme={null}
    <form data-mcp-action="contact_form" id="kontakt-form">
      ...
    </form>
    ```

    Valid types: `contact_form`, `booking`, `newsletter`, `signup`, `purchase`, `quote`, `login`, `search`, `upload`, `support`
  </Accordion>

  <Accordion title="My Calendly / Typeform / HubSpot form isn't being detected">
    Third-party widgets are detected by checking for their JavaScript objects or DOM elements. Make sure:

    * **Calendly:** The Calendly widget script has fully loaded before OpenHermit runs. If Calendly loads slowly, the detection may miss it. The MutationObserver will re-scan when new content appears, so it usually self-corrects within a second.
    * **HubSpot:** The `window.hbspt` object must be present. If HubSpot is loaded via Google Tag Manager with a delay, the detection may miss it.
    * **Typeform:** The embed must use a `<div data-tf-widget>` element or a `tf-widget` element.

    If automatic detection fails, add `data-mcp-action` attributes manually to the container element of the widget.
  </Accordion>

  <Accordion title="The action name detected is wrong or unclear">
    The script tries to name forms from: aria-label → legend text → nearest heading → form ID → form class. If none of these are clear, it falls back to the form type.

    Fix it by editing the action name directly in your dashboard under **Actions → Edit Prompts**, or add an `aria-label` to your form:

    ```html theme={null}
    <form aria-label="Book a Free Consultation">
    ```
  </Accordion>
</AccordionGroup>

***

## Agent prompts

<AccordionGroup>
  <Accordion title="I configured prompts but agents aren't seeing them">
    Prompts are delivered two ways. Check both:

    **Via the manifest:** Fetch your manifest directly and confirm the prompts appear:

    ```
    https://openhermit.com/api/manifest?key=YOUR_API_KEY
    ```

    **Via the DOM:** View the page source after the script loads. Search for `WebMCP Agent Instructions` — you should see a hidden div with your prompts.

    If prompts appear in the manifest but not in the DOM, the script may not be re-running after you saved the prompts. Clear your browser cache and reload the page.
  </Accordion>

  <Accordion title="Can I use different prompts for different pages?">
    Currently, prompts are set per action (not per page). If the same form appears on multiple pages, it shares the same prompts.

    If you need different prompts for the same type of form on different pages, create a second website entry in the dashboard for that specific subdomain or section.
  </Accordion>
</AccordionGroup>

***

## Analytics

<AccordionGroup>
  <Accordion title="Why do I see 0 interactions even though agents are visiting?">
    Agent interactions are only tracked when:

    1. The visiting agent's user-agent string matches a known AI agent pattern (GPTBot, ClaudeBot, etc.)
    2. The agent submits a form or triggers a tracked event

    Most AI agents that browse via screenshots (computer use) don't identify themselves in the user-agent string. OpenHermit only tracks agents that make standard HTTP requests — not headless browser automation.
  </Accordion>

  <Accordion title="I see 'Unknown agent' in my interactions">
    The agent's user-agent string didn't match any known pattern. This can happen with:

    * Custom or internal agent tools
    * New agents not yet in our detection list
    * Agents that spoof a regular browser user-agent

    The interaction is still tracked — it just shows as Unknown.
  </Accordion>
</AccordionGroup>

***

## Account & billing

<AccordionGroup>
  <Accordion title="What's included in the free plan?">
    The free plan includes:

    * 1 website
    * Contact form detection only
    * Up to 1,000 agent interactions per month
    * Basic analytics

    Upgrade to Pro for unlimited websites, all action types, and full analytics.
  </Accordion>

  <Accordion title="Can I delete a website and add it again?">
    Yes. Deleting a website removes all its actions and events permanently. If you re-add the same domain, it starts fresh with a new API key. You'll need to update the script tag on your website with the new key.
  </Accordion>
</AccordionGroup>


# The WebMCP Manifest
Source: https://docs.openhermit.com/guides/webmcp-manifest

What AI agents see when they discover your website.

## What is the manifest?

The WebMCP manifest is a JSON file published at `/.well-known/webmcp.json` on every OpenHermit-enabled website. It's the machine-readable equivalent of a phone book — it tells AI agents exactly what your website can do and how to do it.

AI agents (and any HTTP client) can fetch it directly:

```bash theme={null}
curl https://yourwebsite.com/.well-known/webmcp.json
```

***

## Manifest structure

```json theme={null}
{
  "webmcp_version": "1.0",
  "site": {
    "name": "Acme Corp",
    "domain": "acme.com",
    "description": "We build the best widgets in Switzerland.",
    "agent_instructions": "This website has 2 agent-ready actions. Use contact_form to reach the team or book_consultation to schedule a call."
  },
  "actions": [
    {
      "name": "Contact Form",
      "type": "contact_form",
      "tool_name": "contact_form",
      "description": "Send a message to the Acme Corp team",
      "selector": "#contact-form",
      "page_url": "https://acme.com/contact",
      "enabled": true,
      "before_prompt": "Please have the customer's name, email, and question ready.",
      "success_prompt": "Message sent. The team responds within 24 hours.",
      "failure_prompt": "Try emailing hello@acme.com directly.",
      "next_action": {
        "url": "https://calendly.com/acme/30min",
        "label": "Book a meeting"
      },
      "fields": [
        { "name": "name", "type": "text", "required": true },
        { "name": "email", "type": "email", "required": true },
        { "name": "message", "type": "textarea", "required": true }
      ]
    }
  ]
}
```

***

## How agents find the manifest

OpenHermit makes your manifest discoverable in four ways:

**1. Standard path** — `/.well-known/webmcp.json` (the canonical location any agent can check)

**2. Meta tag** — injected into every page's `<head>`:

```html theme={null}
<meta name="webmcp" content="https://openhermit.com/api/manifest?key=YOUR_KEY" />
```

**3. Link tag** — also in `<head>`:

```html theme={null}
<link rel="webmcp" href="https://openhermit.com/api/manifest?key=YOUR_KEY" />
```

**4. Response header** — on every page response:

```
X-WebMCP: enabled
```

***

## View your manifest

You can view your manifest anytime from the website detail page in the dashboard, or directly at:

```
https://openhermit.com/api/manifest?key=YOUR_API_KEY
```

***

## Disabled actions

Only actions marked as **Active** in your dashboard appear in the manifest. Disabled actions are hidden from agents entirely. Use this to temporarily remove an action without deleting it.

***

## The agent\_instructions field

The `site.agent_instructions` string is a plain-text summary generated automatically from your active actions. Agents that read this first get a high-level understanding of what's available before parsing individual actions.

You can see and customise this in the website detail page (coming soon).


# How the Script Works
Source: https://docs.openhermit.com/how-the-script-works

What happens every time the OpenHermit script loads on a page.

The script (`script.js`) is a self-contained vanilla JavaScript file under 20KB. It runs as an IIFE (immediately invoked function expression) — it never pollutes the global scope and will never break your page.

## Execution order

Every time the script loads on a page, it does the following in sequence:

<Steps>
  <Step title="Ping (immediate)">
    Before anything else, the script fires a POST to `/api/ping` with the current page URL and script version. This confirms the script is correctly installed — your dashboard installation badge updates within seconds.
  </Step>

  <Step title="Inject discoverability tags">
    The script adds machine-readable metadata to the page `<head>` so AI agents can find the manifest:

    ```html theme={null}
    <meta name="webmcp" content="https://openhermit.com/api/manifest?key=YOUR_KEY" />
    <link rel="webmcp" href="https://openhermit.com/api/manifest?key=YOUR_KEY" />
    ```
  </Step>

  <Step title="Detect AI agents">
    The script checks the user-agent string for known AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Operator, and others) and headless browser signals. If an agent is detected, it's recorded with each event.
  </Step>

  <Step title="Scan for forms">
    All `<form>` elements on the page are scanned. For each form, the script:

    * Extracts all input fields (name, type, required, placeholder)
    * Classifies the form type: `contact_form`, `booking`, `newsletter`, `signup`, `purchase`, `quote`, `login`, `search`, `upload`, or `support`
    * Generates a human-readable name from aria-labels, legends, nearby headings, or the form ID
    * Generates a `tool_name` (snake\_case, used in the manifest)
    * Injects `data-mcp-action`, `data-mcp-description`, `data-mcp-params` attributes
  </Step>

  <Step title="Detect third-party widgets">
    The script detects embedded widgets that aren't standard HTML forms:

    | Widget   | Detection method                                      |
    | -------- | ----------------------------------------------------- |
    | Calendly | `window.Calendly` object or `.calendly-inline-widget` |
    | Typeform | `tf-widget` element or typeform embed script          |
    | HubSpot  | `window.hbspt` or `.hs-form`                          |
    | Intercom | `window.Intercom`                                     |
    | Drift    | `window.drift`                                        |
    | Crisp    | `window.$crisp`                                       |
  </Step>

  <Step title="Extract business info">
    The script reads Schema.org JSON-LD from the page (`@type: LocalBusiness`, `Organization`, etc.) to extract the business name, description, address, and phone number. This enriches the manifest.
  </Step>

  <Step title="Sync to OpenHermit">
    All detected actions (and business info) are sent to `/api/actions/sync`. OpenHermit stores new actions or updates existing ones — preserving any agent prompts you've already configured. The API returns your configured prompts back.
  </Step>

  <Step title="Inject agent prompts into DOM">
    Any configured prompts are injected as a hidden off-screen `div` with an `aria-label`. This means both DOM-reading and accessibility-tree-reading agents can find your instructions without any visual impact on the page.
  </Step>

  <Step title="Track form submissions">
    Event listeners are added to form submit buttons. When a form is submitted, a `completion` or `error` event is sent to `/api/events` via `navigator.sendBeacon` (fire-and-forget — never slows down the page).
  </Step>

  <Step title="Watch for dynamic content (SPAs)">
    A `MutationObserver` watches for new content added to the DOM. If a form appears after the initial load (common in React/Vue/Angular apps), the script re-runs detection automatically.
  </Step>
</Steps>

***

## Form type detection

The script classifies forms by scanning their HTML for keyword signals:

| Type           | Signals                                              |
| -------------- | ---------------------------------------------------- |
| `contact_form` | contact, message, inquiry, reach out, get in touch   |
| `booking`      | book, appointment, schedule, reserve, calendar, slot |
| `newsletter`   | newsletter, subscribe, email list, updates, notify   |
| `signup`       | sign up, register, create account, join, membership  |
| `purchase`     | buy, checkout, order, purchase, payment, cart        |
| `quote`        | quote, estimate, calculate, price, cost, proposal    |
| `login`        | login, sign in, password, username                   |
| `search`       | search, find, look for                               |
| `upload`       | upload, attach, file, CV, resume, document           |
| `support`      | support, help, ticket, issue, problem, complaint     |

If no signal matches, the form is classified as `contact_form` by default.

***

## Performance impact

* Script size: **\< 20KB** uncompressed
* Loads `async` — never blocks page rendering
* Uses `sendBeacon` for event tracking — fire-and-forget, zero latency impact
* Only runs after `DOMContentLoaded` — doesn't affect Time to First Byte or FCP

***

## Security

The script never reads or transmits form field values. It only reads:

* Field names, types, and labels (for schema building)
* Page URL and title
* User agent string (for agent detection)
* Schema.org structured data (if present)

Sensitive user input is never captured.


# Introduction
Source: https://docs.openhermit.com/introduction

Make any website discoverable and actionable by AI agents — in 2 minutes.

## The web is changing. Again.

In 2010, websites weren't built for phones. Then smartphones exploded and mobile-responsive design became mandatory — every serious website had to adapt or lose traffic.

In 2014, most websites ran on plain HTTP. Then browsers started marking them "Not Secure" and Google penalised them in search. HTTPS became mandatory almost overnight.

**In 2025, AI agents are browsing the web on behalf of millions of users.** They're trying to book appointments, fill contact forms, compare services, and complete purchases. Right now, 99.9% of websites are invisible to them — agents can't find forms, can't understand what actions are available, and fall back to slow, unreliable screenshot-based automation.

Agent-ready is the next mandatory layer. OpenHermit gets you there in 2 minutes.

***

## What OpenHermit does

OpenHermit is a WebMCP-compliant platform with three parts:

<CardGroup>
  <Card title="Auto-Detection" icon="magnifying-glass">
    A lightweight script scans your pages for forms, booking widgets, and interactive elements automatically.
  </Card>

  <Card title="Machine-Readable Manifest" icon="file-code">
    Publishes a `/.well-known/webmcp.json` manifest so any AI agent can discover your site's actions instantly.
  </Card>

  <Card title="Agent Prompt Control" icon="sliders">
    Configure what agents see before, during, and after every action — and track every interaction in your dashboard.
  </Card>
</CardGroup>

***

## How it works in 60 seconds

1. **Register** your website at [openhermit.com/dashboard](https://openhermit.com/dashboard)
2. **Paste one script tag** into your website's HTML
3. The script scans your pages, detects forms and widgets, and syncs them to OpenHermit
4. AI agents visiting your site read the manifest and interact with your actions
5. You see every interaction in your analytics dashboard

***

## WebMCP — the emerging standard

OpenHermit implements the [WebMCP specification](https://webmachinelearning.github.io/webmcp/), an emerging W3C standard for machine-readable web actions. By being compliant today, your website will be ready when:

* AI agents explicitly look for `/.well-known/webmcp.json` (like they check `robots.txt`)
* Browsers ship native `navigator.modelContext` support
* Agent frameworks from Anthropic, OpenAI, and Google build WebMCP discovery into their default behaviour

The manifest format may evolve. Your business logic — prompts, action configuration, analytics — stays with you on OpenHermit regardless of which protocol wins.

***

## Next steps

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Add OpenHermit to your website in 2 minutes
  </Card>

  <Card title="How the Script Works" icon="code" href="/how-the-script-works">
    Understand what the script does on each page load
  </Card>
</CardGroup>


# Quick Start
Source: https://docs.openhermit.com/quickstart

Add OpenHermit to your website in 2 minutes.

## Step 1 — Create an account

Go to [openhermit.com/register](https://openhermit.com/register) and create a free account.

***

## Step 2 — Add your website

In your dashboard, click **+ Add Website**. Enter your website's name and domain (e.g. `example.com`). OpenHermit generates a unique API key for your site.

***

## Step 3 — Install the script

Copy the generated script tag and paste it into every page of your website, just before the closing `</body>` tag.

```html theme={null}
<!-- OpenHermit WebMCP Script -->
<script
  src="https://openhermit.com/script.js"
  data-api-key="YOUR_API_KEY"
  async>
</script>
```

### Installing in popular frameworks

<Tabs>
  <Tab title="Next.js">
    Add to your root `app/layout.tsx` using the Next.js `Script` component so it loads on every page:

    ```tsx theme={null}
    import Script from 'next/script';

    export default function RootLayout({ children }) {
      return (
        <html>
          <body>
            {children}
            <Script
              src="https://openhermit.com/script.js"
              data-api-key="YOUR_API_KEY"
              strategy="afterInteractive"
            />
          </body>
        </html>
      );
    }
    ```

    Use `strategy="afterInteractive"` — this ensures the script runs after React hydration so dynamically rendered forms are visible.
  </Tab>

  <Tab title="WordPress">
    Add to your theme's `functions.php`:

    ```php theme={null}
    function openhermit_script() {
      echo '<script src="https://openhermit.com/script.js" data-api-key="YOUR_API_KEY" async></script>';
    }
    add_action('wp_footer', 'openhermit_script');
    ```
  </Tab>

  <Tab title="HTML">
    Paste directly before `</body>` in your HTML files:

    ```html theme={null}
    <script
      src="https://openhermit.com/script.js"
      data-api-key="YOUR_API_KEY"
      async>
    </script>
    ```
  </Tab>

  <Tab title="Webflow / Squarespace">
    In your platform's **Custom Code** settings, paste the script tag into the **Footer Code** field. This adds it to every page automatically.
  </Tab>
</Tabs>

***

## Step 4 — Verify installation

After pasting the script, visit any page on your website in a browser. Within a few seconds, your dashboard will show:

<Frame>
  <div>
    ✓ Script active · Last seen just now
  </div>
</Frame>

If the badge stays amber ("Script not yet detected"), check that:

* The script tag is present in your page's HTML source (Ctrl+U / Cmd+U to view source)
* The `data-api-key` matches the key shown in your dashboard
* The script URL is accessible (not blocked by a CSP header)

***

## Step 5 — Visit pages with forms

Visit the pages on your website that contain contact forms, booking widgets, or other interactive elements. The script detects them automatically and they appear in your **Actions** dashboard within seconds.

***

## What's next?

<CardGroup>
  <Card title="Configure Agent Prompts" icon="sliders" href="/guides/agent-prompts">
    Tell agents what to do before, during, and after each action
  </Card>

  <Card title="View Your Manifest" icon="file-code" href="/guides/webmcp-manifest">
    See exactly what AI agents see when they discover your site
  </Card>
</CardGroup>