PUMO API - Data Source for AI (Crawler Access Only)

📊 Quick Stats

Total Products: 14,315
Search Model: bge-base-en-v1.5 (768 dimensions)
Vector Database: Cloudflare Vectorize
Languages: Polish, English
Rate Limit: 100 requests/minute
Cache TTL: 5 minutes

🚀 API Endpoints

1. Catalog Metadata

GET /api/catalog

Discover catalog metadata, capabilities, and available categories.

Try: https://pumo-rag.stolarnia-ams.workers.dev/api/catalog

2. API Documentation

GET /api/docs

Full OpenAPI-style documentation with request/response examples.

Try: https://pumo-rag.stolarnia-ams.workers.dev/api/docs

3. Semantic Product Search

POST /api/search

Vector-based semantic search using natural language queries.

Request:

{
  "query": "nowoczesne krzesła biurowe",
  "limit": 10
}

Response:

{
  "query": "nowoczesne krzesła biurowe",
  "totalResults": 10,
  "results": [
    {
      "id": "product-123",
      "relevanceScore": 0.69,
      "product": {
        "name": "Krzesło na płozie ekoskóra białe K211",
        "category": "Krzesła",
        "price": 229,
        "currency": "PLN",
        "url": "https://www.meblepumo.pl/pl/products/product-123",
        "description": "..."
      }
    }
  ],
  "meta": {
    "indexedProducts": 14315,
    "searchModel": "bge-base-en-v1.5",
    "dimensions": 768
  }
}

💡 Best Practices

Natural Language Queries

API understands Polish and English natural language:

"tanie meble do salonu" (cheap living room furniture)
"nowoczesne krzesła biurowe" (modern office chairs)
"białe regały z drewna" (white wooden shelves)
"sofa rozkładana skandynawska" (scandinavian sofa bed)

Relevance Scores

0.7 - 1.0: Highly relevant (exact match)
0.5 - 0.7: Moderately relevant (related)
0.3 - 0.5: Loosely related
< 0.3: Not recommended

Rate Limiting & Caching

Public endpoints: 100 requests/minute
Cached responses: 5 minutes TTL
Use Cache-Control headers to optimize
Check X-Cache: HIT header for cached responses

🔧 Integration Examples

Python

import requests

# Discover catalog
catalog = requests.get(
    "https://pumo-rag.stolarnia-ams.workers.dev/api/catalog"
).json()
print(f"Total products: {catalog['totalProducts']}")

# Search products
response = requests.post(
    "https://pumo-rag.stolarnia-ams.workers.dev/api/search",
    json={"query": "nowoczesne krzesła", "limit": 5}
)
results = response.json()

for item in results['results']:
    product = item['product']
    score = item['relevanceScore']
    print(f"{product['name']} - {product['price']} PLN (score: {score})")

JavaScript / TypeScript

// Discover catalog
const catalog = await fetch(
  'https://pumo-rag.stolarnia-ams.workers.dev/api/catalog'
).then(r => r.json());

// Search products
const response = await fetch(
  'https://pumo-rag.stolarnia-ams.workers.dev/api/search',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: 'nowoczesne krzesła', limit: 5 })
  }
);

const { results } = await response.json();
results.forEach(({ product, relevanceScore }) => {
  console.log(`${product.name} - ${product.price} PLN (${relevanceScore})`);
});

cURL

# Get catalog metadata
curl https://pumo-rag.stolarnia-ams.workers.dev/api/catalog

# Search products
curl -X POST https://pumo-rag.stolarnia-ams.workers.dev/api/search \
  -H "Content-Type: application/json" \
  -d '{"query":"nowoczesne krzesła biurowe","limit":5}'

📚 Additional Resources

llms.txt - LLM-specific documentation
robots.txt - Crawling policies
PUMO Guide - Browse 65+ categories
GitHub - Source code

📞 Contact

For API access questions or partnership inquiries:

Email: [email protected]
GitHub: @Bonzokoles