> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhermit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /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: *`).