Docs / Agent endpoints

Agent endpoints

Your store can be shopped by external AI agents, not just the chat widget on it. A set of read-only endpoints under fahad-ai/v1/agent, plus an llms.txt guide, let agents like ChatGPT, Claude and Perplexity discover your products from grounded store data. When a shopper is ready to buy, the agent hands off to a human checkout. The agent never holds a cart and never pays.

Why this exists

The same trust rule that governs the on-site assistant applies here: an agent should read real prices, stock and availability rather than guess them. These endpoints expose only published catalogue data, and the search and product lookups reuse the exact same grounded tools as the chat widget, so an external agent sees what a shopper would see. Nothing here mutates the store or charges anyone.

The endpoints

Five GET endpoints are registered under fahad-ai/v1/agent. All are read-only.

GET /agent/llms returns a plain-text usage guide, llms.txt style, that points agents at the feed and states what is allowed.
GET /agent/catalog returns a structured, cacheable product feed of trusted WooCommerce fields.
GET /agent/search reuses search_products and returns grounded product cards.
GET /agent/product reuses get_product_details for a single product.
GET /agent/checkout-handoff builds a link a human opens to add the chosen items and pay.

These endpoints are public by design because they serve read-only published catalogue data, the same data anyone can see by browsing the store. The checkout handoff returns only URLs, so no payment runs agent-side and no personal data leaves.

llms.txt: the usage guide

Point an agent at /agent/llms first. It responds with text/plain and tells the agent where the feed and search live, and that prices, stock and availability must be read, not invented.

GET /wp-json/fahad-ai/v1/agent/llms
Accept: text/plain

# Acme Supply Co AI agent guide

This store welcomes AI shopping agents. Use the read-only endpoints below; all
data is grounded in the live catalogue. Do not fabricate prices, stock, or
availability. Read them here.

Catalogue feed: https://example.com/wp-json/fahad-ai/v1/agent/catalog
Search:         https://example.com/wp-json/fahad-ai/v1/agent/search?q=QUERY
Checkout:       a human completes payment; request /agent/checkout-handoff for a
                link the shopper opens themselves.

The catalogue feed

/agent/catalog returns up to 200 published products as a compact list of trusted fields. The response carries a Cache-Control: public, max-age=300 header, so agents and proxies can cache it for five minutes.

GET /wp-json/fahad-ai/v1/agent/catalog
Accept: application/json

{
  "count": 2,
  "products": [
    {
      "id": 42,
      "name": "Trail Runner Daypack",
      "price": 89.0,
      "on_sale": false,
      "in_stock": true,
      "url": "https://example.com/product/trail-runner-daypack/",
      "short_desc": "A 20L pack for fast, light day hikes."
    },
    {
      "id": 57,
      "name": "Merino Base Layer",
      "price": 49.0,
      "on_sale": true,
      "in_stock": true,
      "url": "https://example.com/product/merino-base-layer/",
      "short_desc": "Lightweight, breathable merino wool."
    }
  ]
}

Search and product lookup

/agent/search takes a q query parameter and reuses the widget's search_products tool, so the agent gets the same grounded product cards a shopper sees in chat.

GET /wp-json/fahad-ai/v1/agent/search?q=daypack
Accept: application/json

{
  "found": 1,
  "products": [
    {
      "id": 42,
      "name": "Trail Runner Daypack",
      "price": "89.00",
      "regular_price": "89.00",
      "sale_price": null,
      "on_sale": false,
      "in_stock": true,
      "short_description": "A 20L pack for fast, light day hikes.",
      "image": "https://example.com/wp-content/uploads/daypack.jpg",
      "url": "https://example.com/product/trail-runner-daypack/",
      "rating": 4.7,
      "review_count": 23
    }
  ]
}

/agent/product takes an id parameter and reuses get_product_details for a single product, including variations where they exist.

GET /wp-json/fahad-ai/v1/agent/product?id=42
Accept: application/json

The human checkout handoff

When the shopper has chosen what they want, the agent calls /agent/checkout-handoff with a comma-separated ids list. The endpoint returns a WooCommerce add-to-cart link per product. A person opens those links in a browser, which populates their own cart in their own session, then they check out and pay themselves.

GET /wp-json/fahad-ai/v1/agent/checkout-handoff?ids=42,57
Accept: application/json

{
  "note": "Open these links in a browser to add the items and check out. Payment is completed by the shopper, not the agent.",
  "items": [
    {
      "product_id": 42,
      "add_to_cart": "https://example.com/cart/?add-to-cart=42"
    },
    {
      "product_id": 57,
      "add_to_cart": "https://example.com/cart/?add-to-cart=57"
    }
  ]
}

This boundary is deliberate. The agent assembles intent and surfaces links, but the cart, the session and the payment all belong to the human. Passing an empty or missing ids list returns a 400 error.

A typical agent flow

Read /agent/llms to learn the rules and where to look.
Pull /agent/catalog for a cacheable overview, or call /agent/search?q=... for a specific need.
Confirm a candidate with /agent/product?id=....
Hand the shopper a link from /agent/checkout-handoff?ids=... to add the items and pay.

← All docs REST API →