Introducing the Agenticfeed Agent Query API

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",
  "anthropic_api_key": "sk-ant-your-key",
  "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. It passes all of that to Claude along with the buyer's query and asks it to find the best matches. The response comes back as 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 — the explanation is already written.

You Bring Your Own Anthropic Key

One design decision worth explaining: the API requires callers to supply their own Anthropic API key in the request body. Agenticfeed validates it with a minimal check, then uses it for the matching call. You pay Anthropic directly at their standard rates for claude-haiku-4-5-20251001. A typical query costs a fraction of a cent.

This was a deliberate choice. Most developers building AI agents already have an Anthropic account. They are already paying for AI compute elsewhere in their application. Routing the matching call through their own key keeps their billing in one place and means Agenticfeed does not mark up AI costs or act as an intermediary.

Agenticfeed's role is the data and the matching infrastructure. The AI compute is yours.

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 was generated by Claude when the merchant's feed was created and updated monthly.

All of that is sent to Claude Haiku with a structured prompt: here is what the buyer needs, here is the product catalogue with intent data, find the best matches and explain each one. Claude returns a ranked list of product IDs and match reasons. Agenticfeed then fetches the full product records, builds the schema.org response, and returns it.

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 — 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 — 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 available to developers now. You need two things:

1. An Agenticfeed API key — email sales@bluestratus.com with a brief description of what you are building
2. An Anthropic API key from console.anthropic.com

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.