API v1.0.0

Bowlly Agent API

Clean, affiliate-free product data for AI agents and applications. Access comprehensive cat food information without tracking links.

Quick Start

Make your first request anonymously, or add an API key for higher rate limits:

curl "https://api.bowlly.net/agent/products?limit=5"

curl -H "X-API-Key: your_api_key_here" "https://api.bowlly.net/agent/products?limit=5"

Example response:

{
  "items": [
    {
      "id": "product-123",
      "name": "Premium Cat Food",
      "brand": "Acme",
      "detailUrl": "https://bowlly.net/products/product-123?src=agent",
      "imageUrl": "https://bowlly.net/api/images/product-123-thumb.jpg",
      "form": "dry",
      "lifeStageTags": ["adult"],
      "conditionTags": ["sensitive"],
      "nutrition": {
        "protein": 40,
        "fat": 20,
        "fiber": 3,
        "moisture": 10
      },
      "derivedMetrics": {
        "meatScore": 85,
        "carbEstimated": 15
      }
    }
  ],
  "meta": {
    "total": 1500,
    "offset": 0,
    "limit": 20,
    "hasMore": true,
    "query": { "search": "", "filters": {} },
    "executionTimeMs": 45,
    "apiVersion": "1.0.0",
    "timestamp": "2026-02-19T12:00:00Z"
  }
}

Authentication

🔐

API Key Optional

Agent API endpoints allow anonymous read requests with lower rate limits. Pass an API key in the X-API-Key header for higher limits and authenticated agent context. Public self-serve key issuance is not available yet.

curl -H "X-API-Key: your_api_key_here" "https://api.bowlly.net/agent/products?limit=5"

Authentication Errors

Status	Description	Response
401	Invalid or revoked API key when one is provided	{ error: "Invalid or revoked API key" }

Rate Limiting

⏱️

Anonymous and API-Key Limits

Anonymous requests use lower limits to keep the public API available. API keys use the key-specific limit when configured, or the environment default. Production defaults are 20 requests per minute for anonymous requests and 100 requests per minute for API-key requests.

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

{
  "error": "Rate limit exceeded. Please try again later.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Need higher limits? Contact us at contact@bowlly.net

Base URL

Production

https://api.bowlly.net

Development

http://localhost:3001

Endpoints

GET/agent/products

List products with optional filtering and pagination.

Query Parameters

Parameter	Type	Default	Description
offset	integer	0	Number of results to skip
limit	integer	20	Number of results to return (max 50)
search	string	-	Search term for product name/brand
form	string	-	Filter by form: "dry" or "wet"
grainFree	boolean	-	Filter for grain-free products only
primaryProtein	string	-	Filter by primary protein (e.g., "chicken", "salmon")
minProtein	number	-	Minimum protein percentage
maxProtein	number	-	Maximum protein percentage
minMeatScore	number	-	Minimum meat score (0-100)
maxMeatScore	number	-	Maximum meat score (0-100)
conditions	string	-	Comma-separated condition tags
agent	string	-	Identifies calling agent (e.g., "chatgpt", "claude")

Scalability Notes

Current `/agent/products` uses active-catalog query + in-memory filtering for MVP speed. For stable latency, keep active catalog around ~500 products. Above that, we recommend filter-specific indexes or a dedicated search service.

Response Format

Product Object

{
  "id": "string",           // Unique product identifier
  "name": "string",         // Product name
  "brand": "string",        // Brand name
  "detailUrl": "string",    // Bowlly product page URL (with src=agent)
  "imageUrl": "string",     // Thumbnail image URL (optional)
  "form": "dry" | "wet",    // Product form (optional)
  "lifeStageTags": [],      // Array of life stage tags (optional)
  "conditionTags": [],      // Array of condition tags (optional)
  "nutrition": {            // Nutritional data (optional)
    "protein": number,      // Protein percentage
    "fat": number,          // Fat percentage
    "fiber": number,        // Fiber percentage
    "moisture": number,     // Moisture percentage
    "phosphorusAsFed": number // Phosphorus as-fed percentage when available
  },
  "derivedMetrics": {       // Computed metrics (optional)
    "meatScore": number,    // 0-100 meat content score
    "carbEstimated": number // Estimated carbohydrate percentage
  }
}

Product Detail Extension

{
  "product": {
    "...AgentProduct": "...",
    "ingredientsPreview": ["chicken", "chicken broth"],
    "ingredientsFull": ["chicken", "chicken broth", "liver"],
    "energyKcalPerKg": 1020,
    "hasOffer": true
  }
}

Compare Response

{
  "products": [],
  "compared": 2,
  "requested": 2
}

Meta Object

{
  "total": number,          // Total matching products
  "offset": number,         // Current offset
  "limit": number,          // Results per page
  "hasMore": boolean,       // Whether more results exist
  "query": {                // Applied query parameters
    "search": "string",
    "filters": {}
  },
  "executionTimeMs": number,// Query execution time
  "apiVersion": "string",   // API version
  "timestamp": "string"     // ISO 8601 response timestamp
}

Error Handling

Status	Description	Response
200	Success	{ items: [], meta: {} }
400	Bad Request	{ error: "Invalid parameter" }
429	Rate Limited	{ error: "Rate limit exceeded" }
500	Server Error	{ error: "Internal server error" }

Example Requests

Basic Request

GET /agent/products?limit=10

With Search Filter

GET /agent/products?search=grain-free&form=dry&limit=20

With Pagination

GET /agent/products?offset=20&limit=20

With Agent Identification

GET /agent/products?agent=chatgpt&limit=5

The agent parameter helps us understand API usage patterns and optimize for different AI platforms.

Complex Filter

GET /agent/products?form=dry&minProtein=35&grainFree=true&conditions=sensitive,urinary

GPT Actions Integration

🤖

Use with ChatGPT Custom GPTs

This API is designed for integration with ChatGPT Custom GPTs. Use the OpenAPI specification below to configure your GPT Action.

OpenAPI Spec:/gpt-actions.yaml

CORS is stage-based allowlist. GPT Actions/server-side integrations work without browser CORS dependencies.

MCP Server (Claude Desktop / Cursor)

🛠️

Use as MCP tools inside your client

Prefer a tool-based workflow? Install the MCP server and use Bowlly tools directly in Claude Desktop or Cursor.

Quick setup:

npx @bowlly/mcp-server --setup

Setup guide: /mcp·npm: @bowlly/mcp-server

Important Notes

🔗

No Affiliate Links

Responses contain no affiliate links or tracking tags. Product URLs point to Bowlly product pages with src=agent tracking for analytics only.

🖼️

Image Proxies

Image URLs are Bowlly-hosted proxies for consistent availability and performance.

🤖

Built for AI Agents

This API is designed specifically for AI agents and applications that need clean, structured product data without commercial bias.