# Krawfly — Complete Documentation

> Krawfly is the universal GEO infrastructure for e-commerce catalogs. It scans product data, publishes AI-ready signals and runs visibility and citation checks across Shopify, WooCommerce, Magento, PrestaShop and custom stacks.

## Overview

Krawfly helps e-commerce brands move from classic store discovery to measurable AI visibility. The platform:
- Scans product catalogs and computes AI readiness (GEO Score 0-100)
- Identifies missing signals that cause products to be ignored by generative engines
- Generates AI-ready product context (titles, descriptions, keywords, FAQ signals, comparison points)
- Publishes approved catalog signals server-side via JSON-LD injection
- Tracks AI crawler activity (GPTBot, PerplexityBot, ClaudeBot) on client sites
- Checks whether products are cited by Perplexity, Gemini and ChatGPT

## Products

### 1. Shopify App
Native Shopify Admin embedded app. Merchants install via the Shopify App Store, connect their catalog, and Krawfly scans products automatically. AI-optimized signals are applied directly via the Shopify Admin API. Supports multi-locale markets.

### 2. Agency Dashboard
Multi-client interface at dashboard.krawfly.com. Agencies upload client catalogs (CSV/API), trigger bulk scans, review AI analysis results, and manage GEO optimization across any e-commerce platform — Shopify, WooCommerce, Magento, PrestaShop, headless.

### 3. Krawfly Edge
Cloudflare Worker installed on client sites. Intercepts HTML requests and injects AI-ready JSON-LD structured data server-side — before the response reaches the browser. Zero latency impact. Works without modifying the site's codebase.

### 4. llms.txt Generator
Free public tool at krawfly.com/tools/llms-txt. Generates a structured llms.txt file for any domain, readable by AI agents.

## Technical Architecture

- **API**: REST API at api.krawfly.com — Fastify, BullMQ queue, Drizzle ORM
- **AI Pipeline**: Gemini 2.5 Flash (primary) + OpenAI (fallback) for text and vision analysis
- **SERP**: Brave Search API for competitor and SERP snapshot data
- **Citation check**: Perplexity API for AI citation verification
- **Edge**: Cloudflare Workers for server-side JSON-LD injection
- **Platforms**: Shopify (webhook + Admin API), WooCommerce, Magento, PrestaShop, headless via CSV/API

## API Reference

Base URL: https://api.krawfly.com
Authentication: OAuth2 (authorization_code, client_credentials) or API key (x-krawfly-secret)
OpenAPI spec: https://api.krawfly.com/openapi.json
Documentation: https://api.krawfly.com/docs

### Key Endpoints

**POST /api/v1/scan-product**
Trigger a GEO scan for a single product. Returns jobId for async result retrieval.

**POST /api/v1/init-scan-catalog**
Trigger a bulk catalog scan.

**POST /api/v1/products/retrieval/ai-result**
Retrieve AI analysis results for a product (scores, suggestions, issues).

**POST /api/v1/edge/signals**
Get AI-ready JSON-LD for a product URL (used by Krawfly Edge Worker).

**POST /api/v1/monitoring/citation-trigger**
Trigger a citation check across Perplexity for a shop's products.

**GET /api/v1/monitoring/citation-results**
Retrieve citation check results.

## GEO Score Formula

`GEO Score = (keyword_confidence × 35) + (serp_tracked ? 25 : 0) + contentReadiness(0–20) + aiMaturity(0–10) − issuePenalty`

Scores:
- 0–30: Not AI-ready
- 31–60: Partial readiness
- 61–80: Good AI visibility
- 81–100: Fully AI-ready (eligible for citation)

## Pricing

- **Free**: 10 products, basic scan
- **Starter**: €29/month — 100 products, SERP tracking, single locale
- **Pro**: €79/month — 500 products, multi-locale, citation tracking, impact analytics
- **Enterprise**: custom — unlimited products, agency dashboard, priority support

Trial: 7 days free on any plan.

## Primary Pages

- [Home](https://krawfly.com/) — Product overview, GEO positioning, workflow, pricing
- [GEO for Shopify](https://krawfly.com/geo-for-shopify) — Shopify-specific GEO optimization
- [What is GEO](https://krawfly.com/what-is-geo) — Definition and context for Generative Engine Optimization
- [GEO vs SEO](https://krawfly.com/geo-vs-seo) — How GEO differs from classic SEO
- [Platforms](https://krawfly.com/platforms) — All supported e-commerce platforms
- [Pricing](https://krawfly.com/pricing) — Plan comparison
- [Privacy Policy](https://krawfly.com/privacy)
- [Terms of Service](https://krawfly.com/terms)
- [llms.txt Generator](https://krawfly.com/tools/llms-txt) — Free public tool
- [Blog](https://krawfly.com/blog) — GEO education and platform updates

## Platform Pages

- [Shopify GEO](https://krawfly.com/platforms/shopify)
- [WooCommerce GEO](https://krawfly.com/platforms/woocommerce)
- [Magento AI](https://krawfly.com/platforms/magento)
- [PrestaShop GEO](https://krawfly.com/platforms/prestashop)
- [Custom/Headless](https://krawfly.com/platforms/custom)

## Blog Articles

### English
- [GEO vs SEO](https://krawfly.com/blog/geo-vs-seo) — Structural difference between search ranking signals and AI recommendation signals; why the same catalog needs separate optimization for each
- [GEO for Ecommerce](https://krawfly.com/blog/geo-for-ecommerce) — Three-step framework to make a product catalog AI-recommendable: llms.txt, semantic richness, JSON-LD structured data
- [What is GEO in Ecommerce](https://krawfly.com/blog/what-is-geo-in-ecommerce) — How generative engines change product discovery and what AI-ready infrastructure requires
- [How ChatGPT Recommends Products](https://krawfly.com/blog/how-chatgpt-recommends-products) — How AI agents evaluate product data and what signals drive recommendations
- [What is llms.txt](https://krawfly.com/blog/what-is-llms-txt) — llmstxt.org specification, what to include for ecommerce, and how AI models use the file
- [Does llms.txt Actually Help](https://krawfly.com/blog/does-llmstxt-actually-help) — Honest assessment: what llms.txt can and cannot do for AI visibility, which systems read it today

### Italian
- [GEO vs SEO (IT)](https://krawfly.com/it/blog/geo-vs-seo)
- [GEO per Ecommerce (IT)](https://krawfly.com/it/blog/geo-per-ecommerce)
- [Come ChatGPT Raccomanda Prodotti (IT)](https://krawfly.com/it/blog/come-chatgpt-raccomanda-prodotti)
- [Cosa è llms.txt (IT)](https://krawfly.com/it/blog/cosa-e-llms-txt)

### Spanish
- [GEO vs SEO (ES)](https://krawfly.com/es/blog/geo-vs-seo)
- [GEO para Ecommerce (ES)](https://krawfly.com/es/blog/geo-para-ecommerce)
- [Qué es GEO en Ecommerce (ES)](https://krawfly.com/es/blog/que-es-geo-en-ecommerce)
- [Qué es llms.txt (ES)](https://krawfly.com/es/blog/que-es-llms-txt)
- [llms.txt ayuda visibilidad IA (ES)](https://krawfly.com/es/blog/llmstxt-ayuda-visibilidad-ia)

## Key Concepts

- **GEO**: Generative Engine Optimization — making products readable, comparable and measurable for AI agents
- **GEO Readiness**: how prepared a product is for generative engines
- **Product Signals**: structured semantic context AI agents can read and cite
- **AI Citation**: when an AI assistant (Perplexity, ChatGPT, Gemini) explicitly cites or recommends a product in response to a query
- **JSON-LD injection**: server-side injection of Schema.org structured data into product page HTML
- **llms.txt**: a machine-readable text file (Markdown format) that describes a site's content and capabilities for AI agents

## Contact

- Support: support@krawfly.com
- Info: info@krawfly.com
- Site: https://krawfly.com