Hints file reference

A hints file describes operations, private regions and theme values that discovery cannot see. Serve it as JSON from the same origin as your page and set its path (for example /agent-hints.json) in the site’s settings. The loader’s data-hints-url attribute is used only when the site has no configured path. The file is fetched without caching; a cross-origin URL is ignored.

Example

{
  "version": 2,
  "apiOrigins": ["https://api.example.com"],
  "privateSelectors": ["#login-form", ".billing-details"],
  "operations": [
    {
      "id": "inventory.list",
      "name": "List inventory items",
      "description": "Read one page of inventory items. Returns {items, page, totalPages}.",
      "effect": "read",
      "api": {
        "kind": "api",
        "origin": "https://api.example.com",
        "method": "GET",
        "pathTemplate": "/items",
        "querySchema": {
          "type": "object",
          "properties": { "page": { "type": "integer", "minimum": 1 } }
        },
        "credentialHeaders": ["x-csrf-token"]
      },
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "object",
            "properties": { "page": { "type": "integer", "minimum": 1, "description": "1-based page number" } }
          }
        },
        "additionalProperties": false
      }
    },
    {
      "id": "inventory.updatePrice",
      "name": "Update item price",
      "description": "Set the price of one inventory item in USD.",
      "effect": "write",
      "api": {
        "kind": "api",
        "origin": "https://api.example.com",
        "method": "PATCH",
        "pathTemplate": "/items/{id}",
        "pathSchema": {
          "type": "object",
          "properties": { "id": { "type": "integer" } },
          "required": ["id"]
        },
        "bodySchema": {
          "type": "object",
          "properties": { "price": { "type": "number", "minimum": 0 } },
          "required": ["price"]
        }
      },
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": { "type": "object", "properties": { "id": { "type": "integer" } }, "required": ["id"] },
          "body": { "type": "object", "properties": { "price": { "type": "number", "minimum": 0 } }, "required": ["price"] }
        },
        "required": ["path", "body"],
        "additionalProperties": false
      },
      "ui": {
        "kind": "dom",
        "steps": [
          { "op": "fill", "target": { "selector": "#open-item-id" }, "value": { "from": "/path/id" } },
          { "op": "submit", "target": { "selector": "#open-item-form" } },
          {
            "op": "wait",
            "target": { "selector": "#edit-form[data-item-id=\"{{/path/id}}\"]" },
            "property": "visible",
            "equals": { "literal": true },
            "timeoutMs": 5000
          },
          { "op": "fill", "target": { "selector": "#edit-price" }, "value": { "from": "/body/price" } },
          { "op": "submit", "target": { "selector": "#edit-form" } }
        ]
      }
    }
  ],
  "theme": { "accent": "#1f6feb", "radius": "6px" }
}

Top-level fields

Unknown fields anywhere in the file are rejected.

Field	Type	Limits
version	2	Required. Other versions are rejected.
apiOrigins	origin strings	Up to 16. API origins your operations call.
operations	operation objects	Up to 200.
privateSelectors	CSS selectors	Up to 100, each 1-256 characters. Matching parts of the page are never read.
theme	object	Optional fontFamily (200), foreground, background, accent (64 each), radius (32 characters).

Origins are exact (https://api.example.com): no path, wildcard or trailing slash. An operation can only call the page origin or an API origin also allowed in your site’s settings.

Operations

Field	Type	Limits
id	string	Required. 1-128 characters from A-Z a-z 0-9 _ . : -.
name	string	Required. 1-128 characters.
description	string	Required. Up to 1000 characters.
effect	read, write or unknown	Required. Writes and unknowns are shown to the user for approval.
api	API binding	Required.
inputSchema	schema	Required. The arguments the assistant passes: path, query and body objects.
outputSchema	schema	Optional. The shape of the response.
ui	DOM recipe	Optional. Steps that perform the operation through the page’s own UI.

Classify effect carefully: marking a write as read removes the user’s review.

API binding

Field	Type	Notes
kind	"api"	Required.
origin	origin	Required.
method	GET, HEAD, POST, PUT, PATCH, DELETE	Required.
pathTemplate	string	Required. Starts with /, up to 512 characters. Placeholders are whole {name} segments filled from path.
pathSchema, querySchema, bodySchema	schema	Optional.
staticHeaders	object	Optional fixed, non-secret headers. Lowercase names, values up to 256 characters.
credentialHeaders	lowercase header names	Up to 8. Values come only from headers your app already sent or from getAuthHeaders; they never reach the model.

Supported schema subset

Schemas use this subset of JSON Schema, nested at most 8 levels deep:

• type (string, number, integer, boolean, object, array, null, or an array of them)
• properties, required, additionalProperties (false or a schema), items
• enum (1-100 values), const, default
• minimum, maximum, minLength, maxLength, minItems, maxItems
• title (200 characters), description (4000 characters; long descriptions are shortened in the assistant’s catalog)
• $defs with local $ref values of the form #/$defs/name

Property names are 1-128 characters. Any other keyword is rejected.

DOM recipes

A ui recipe is { "kind": "dom", "steps": [...] } with 1-32 steps. Each step has a target of { "selector": "..." } (up to 512 characters). A {{/pointer}} placeholder in a selector is replaced with the escaped argument value at that JSON pointer.

op	Extra fields
read	resultKey
click, submit	none
fill, check, select	value
press	key: Enter or Escape
wait	property (value, text or visible), equals, timeoutMs (0-10000)

Values are { "from": "/body/price" }, a JSON pointer into the operation’s arguments, or { "literal": ... }.