Action Manifest

The Action Manifest is Layer 2 of Hunch's action dispatch system. It lets site owners explicitly declare their API endpoints, giving the widget the highest-trust execution path.

What It Is

A hunch-actions.json file is a structured JSON document that describes the actions a website supports. When present, the widget uses these declarations instead of discovering endpoints through other means.

Owner-declared endpoints receive confidence 1.0 — the highest possible trust level.

How to Create a Manifest

Option 1: Admin Dashboard

The easiest way to create a manifest:

1. Go to Admin → Action Manifests
2. Select your website
3. Add actions using the form editor
4. Click Save

The manifest is stored in Hunch's database and served to the widget automatically.

Option 2: Manual JSON File

Create a hunch-actions.json file and place it at your domain root (https://yourdomain.com/hunch-actions.json).

Manifest Schema

{
  "version": "1.0.0",
  "actions": [
    {
      "name": "submit_contact",
      "method": "POST",
      "path": "/api/contact",
      "description": "Submit the contact form",
      "params": {
        "name": { "type": "string", "required": true },
        "email": { "type": "email", "required": true },
        "message": { "type": "string", "required": true }
      },
      "auth": {
        "cookies": "automatic",
        "csrf": {
          "source": "meta",
          "selector": "meta[name='csrf-token']",
          "header": "X-CSRF-Token"
        }
      },
      "confirmationRequired": false
    }
  ]
}

Action Fields

Field	Type	Required	Description
name	string	Yes	Unique identifier for the action
method	string	Yes	HTTP method: GET, POST, PUT, DELETE, PATCH
path	string	Yes	API endpoint path (relative to domain root)
description	string	Yes	Human-readable description
params	object	No	Parameter definitions with type and required flag
auth	object	No	Authentication configuration
confirmationRequired	boolean	No	Require user confirmation before execution
confirmationMessage	string	No	Custom confirmation message

Parameter Types

Type	Description
string	General text input
number	Numeric input
boolean	True/false toggle
email	Email address (validated)
date	Date value
select	Dropdown selection

Authentication

If your API requires authentication:

{
  "auth": {
    "cookies": "automatic",
    "csrf": {
      "source": "meta",
      "selector": "meta[name='csrf-token']",
      "header": "X-CSRF-Token"
    }
  }
}

The widget resolves CSRF tokens from the page automatically. Supported sources:

• meta — Reads from a <meta> tag
• input — Reads from a hidden <input> field
• cookie — Reads from a cookie
• endpoint — Fetches from a dedicated CSRF endpoint

Loading Priority

The widget loads manifests in this order:

1. Hunch API (/manifest/:websiteId) — Stored via admin dashboard
2. Domain root (/hunch-actions.json) — Manual deployment
3. Session cache — Previously loaded manifest cached in sessionStorage

When to Use a Manifest

Use a manifest when:

• Your API endpoints are stable and well-documented
• You want maximum execution reliability
• Your site has custom authentication (CSRF tokens, API keys)
• You want to control exactly which actions are exposed

You do not need a manifest when:

• Your site is on Shopify or WooCommerce (platform APIs are detected automatically)
• Your forms are simple HTML forms (DOM-native execution handles them)
• You are still iterating on your API (passive capture learns from real usage)

Validation

The admin dashboard validates manifests before saving. Manual JSON files are validated when the widget loads them. Invalid manifests are rejected with specific error messages.

Common validation errors:

• Missing version field
• Missing or empty actions array
• Action missing required name, method, path, or description
• Invalid HTTP method
• Invalid CSRF source type

Related

• Live Action Capture — Four-layer architecture overview
• DOM-Native Execution — Layer 0 fallback
• Tools — Manage discovered tools
• Privacy and Compliance — Data handling policies