Introducing the Agenticfeed Agent Query API
Until now, Agenticfeed has been a passive data layer. AI agents could discover and crawl your product feed, but the conversation was one-sided: the agent did all the work. The Agent Query API changes that. An AI agent can now send a plain English description of what a buyer needs and get back matched products with reasons, in a single request.
Passive versus Active
The original Agenticfeed model works like a library. Merchants put their product data on the shelves. AI agents visit, browse the catalogue, and piece together recommendations on their own. That works, and it is how most structured data on the web operates today.
The Agent Query API is different. It is more like calling a knowledgeable assistant. You describe the buyer's situation and ask for the best matches. The API searches the catalogue, reasons about which products best fit the intent, and tells you why each one was chosen. You do not need to understand the data structure, crawl multiple endpoints, or do any matching yourself.
Both approaches are now supported. The passive feed stays in place for agents that prefer to crawl. The query API is there for agents that want a direct answer.
How It Works
You send a POST request to /agent/query with a natural language description of the buyer's need:
POST https://agenticfeed.ai/agent/query
Authorization: Bearer af_your_api_key
Content-Type: application/json
{
"query": "board game for a family with children aged 8 to 12, 3 to 5 players, under £35",
"limit": 3
}
Agenticfeed fetches the merchant's product catalogue and intent data from the database: the questions each product answers, the problems it solves, the use cases it fits. The Agenticfeed matching engine reasons about which products best fit the buyer's intent and returns a schema.org ItemList:
{
"@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",
"offers": {
"@type": "Offer",
"price": "34.99",
"priceCurrency": "GBP",
"availability": "https://schema.org/InStock"
},
"agenticfeed": {
"match_reason": "Suitable for 2 to 5 players aged 8 and up, plays in under 75 minutes, and falls within the stated budget."
}
}
]
}
The match_reason field is designed to be passed directly to the buyer. The calling agent does not need to do any additional reasoning, because the explanation is already written.
What the Matching Actually Does
When a query arrives, Agenticfeed fetches up to 50 products from the merchant's catalogue, each with up to five questions, five problems, and five use cases. This intent data is generated when the merchant's feed is created and refreshed monthly on paid plans.
The Agenticfeed matching engine processes the buyer's intent against the full product catalogue, finds the best matches, and explains each one. The match reasons are written for the buyer, so the calling agent can pass them through directly without any additional processing.
The whole process takes about two to three seconds for a typical query against a 50-product catalogue. The response is ready-made structured data, with no post-processing needed.
What You Can Build With It
The query API opens up a category of applications that was not practical before.
AI shopping assistants. A chatbot on a retail website that understands what the customer is describing and surfaces the right products. Not keyword search. Not filters. Actual reasoning about the buyer's situation.
Conversational product recommendation. An AI assistant that asks the buyer a few questions, builds up a description of their need, then calls the query API to find the best match. The kind of experience that used to require a trained sales consultant.
Multi-merchant product discovery. An agent that queries multiple Agenticfeed-powered merchant catalogues in parallel, compares results, and recommends the best option across different stores. Comparison shopping, but driven by intent rather than price filtering.
Integration with AI platforms. Any AI agent or workflow that needs to resolve a natural language product request to a specific buyable item. The response is schema.org so it integrates cleanly with any system that understands structured data.
Attribution Is Built In
Every product URL in the query response is automatically tagged with UTM parameters:
utm_source=agenticfeed&utm_medium=ai-agent
When a buyer clicks through from an agent recommendation and places an order, that sale is attributed to Agenticfeed in the merchant's analytics. Merchants can see exactly which products are being recommended by AI agents and which ones are converting. The query API does not change this, and attribution works the same way it does for the passive feed.
The Agent Card
Alongside the query endpoint, Agenticfeed now publishes an Agent Card at https://agenticfeed.ai/.well-known/agent.json. This is a machine-readable description of what the agent can do: what inputs it accepts, what it returns, and how to authenticate.
Agent Cards are part of Google's Agent-to-Agent (A2A) protocol, an emerging standard for AI agents to discover and communicate with each other without human configuration. An AI platform that implements A2A can find the Agenticfeed query endpoint automatically by reading the card, without anyone hard-coding the URL.
This is early. A2A is still being adopted. But having the card in place now means Agenticfeed is ready when platforms start looking for it.
Getting Access
The query API is included with all paid Agenticfeed plans (Growth and above). If you are a merchant or developer on a paid plan, go to Dashboard › API Keys to generate your key instantly, with no approval required.
Full documentation is at agenticfeed.ai/api.html including request format, response schema, and a curl example. The underlying feed format is also published as an open standard at github.com/bluestratus/agenticfeed.