Agent Query API — Developer Docs

What this API does

The Agenticfeed passive feed lets AI agents crawl product data by following URLs. The Agent Query API is the active layer. Your AI sends a plain English description of what a buyer needs and gets back the best matching products from a merchant's catalogue — with a reason for each match that you can pass directly to the buyer.

The Agenticfeed matching engine processes the buyer's intent against the merchant's product catalogue and returns ranked matches with reasons. The API is included with all paid Agenticfeed plans — no additional cost per query.

The response is a schema.org ItemList of Product entries. Every product URL is UTM-tagged so the merchant can see traffic and orders originating from AI agent recommendations in their analytics.

Getting started

Sign up for a paid Agenticfeed plan Create an account at agenticfeed.ai/login.html and subscribe to Growth or above. The Agent Query API is included with all paid plans.
Generate your API key Go to Dashboard › API Keys and generate a key instantly. No approval process — your key is ready in seconds.
Make your first query Send a POST request to /agent/query with your buyer's intent. See the request format below.

Authentication

Every request requires two keys:

Agenticfeed API key

Passed as a Bearer token in the Authorization header. This is your access credential that identifies your account and which merchant feeds you can query. Generate it in Dashboard › API Keys — it takes seconds, no approval needed.

Authorization: Bearer af_your_api_key_here

Query endpoint

POST https://agenticfeed.ai/agent/query

Request body

{
  "query": "ergonomic chair for someone with lower back pain, works from home 10 hours a day, small home office, budget under £300",
  "customer_guid": "a9a8378c94",
  "limit": 5
}

Field	Type	Description
query required	string	Natural language description of what the buyer needs. The more specific, the better the matches.
customer_guid	string	The merchant feed to query. Defaults to the feed linked to your Agenticfeed API key if omitted.
limit	integer	Maximum products to return. Between 1 and 10. Default is 5.

Full request example

curl -X POST https://agenticfeed.ai/agent/query \
  -H "Authorization: Bearer af_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "board game for a family with children aged 8 to 12, 3 to 5 players, under £35",
    "limit": 3
  }'

Response

Returns application/ld+json — a schema.org ItemList of matched Product entries ordered by relevance. Each product includes a match_reason field explaining why it fits the buyer's need. This is designed to be passed directly to the end buyer by the calling agent.

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "query": "board game for a family with children aged 8 to 12...",
  "numberOfItems": 2,
  "itemListElement": [
    {
      "@type": "Product",
      "position": 1,
      "name": "Ticket to Ride Europe",
      "url": "https://merchant.com/ticket-to-ride?utm_source=agenticfeed&utm_medium=ai-agent",
      "image": "https://merchant.com/images/ttr.jpg",
      "category": "board games",
      "offers": {
        "@type": "Offer",
        "price": "34.99",
        "priceCurrency": "GBP",
        "availability": "https://schema.org/InStock"
      },
      "agenticfeed": {
        "product_id": "b3f1e29a4c",
        "match_reason": "Suitable for 2 to 5 players aged 8 and up, plays in 45 to 75 minutes, and falls within the stated budget."
      }
    }
  ]
}

If no products match the query, itemListElement is an empty array and numberOfItems is 0. No error is returned.

UTM attribution

Every product URL in the response is automatically tagged with UTM parameters:

utm_source=agenticfeed&utm_medium=ai-agent

When a buyer clicks through and makes a purchase, that order is attributed to agenticfeed in the merchant's analytics. This lets merchants measure exactly how much revenue AI agent recommendations are generating.

Agent Card

Agenticfeed publishes an A2A-compatible Agent Card at a standard well-known URL. AI platforms that support Google's Agent-to-Agent protocol can discover and call the query endpoint automatically using this file.

GET https://agenticfeed.ai/.well-known/agent.json

The card describes the agent's capabilities, accepted inputs, output format, and authentication requirements in a machine-readable format.

Open standard

The feed format this API is built on is published as an open specification. You can read the full standard, implement your own compatible feed, or contribute at:

github.com/bluestratus/agenticfeed

The merchant docs covering the rel="agenticfeed" discovery tag and feed format are at agenticfeed.ai/docs.html.

Questions

Email sales@bluestratus.com to request API access or ask about integration. Include a brief description of what you are building.