# YELLOW.bot — Full API Documentation for LLM Agents

## Overview
YELLOW.bot is a bot-first business registry. Register for a free API key
to query company data across industries.

## Endpoints

### 1. POST /api/v1/query
Structured query for business listings.

Request:
```json
{
  "category": "energy/pv-modules",
  "country": "DE",
  "role": "manufacturer",
  "verified": true,
  "sort": "trust_desc",
  "limit": 25,
  "offset": 0
}
```

Response:
```json
{
  "category": { "slug": "energy/pv-modules", "display_name": "PV Modules" },
  "total": 12,
  "limit": 25,
  "offset": 0,
  "listings": [
    {
      "brand": "LONGi Green Energy",
      "role": "manufacturer",
      "country_code": "CN",
      "country_name": "China",
      "description": "...",
      "website_url": "...",
      "provider_id": "YB-90123-CN",
      "verification_status": "verified",
      "trust_score": 0.95
    }
  ]
}
```

### 2. GET /api/v1/search?q=solar+panels
Full-text search across all providers and listings.
Returns matching providers with relevance ranking.

### 3. GET /api/v1/categories
List all available categories.

### 4. POST /api/v1/agents/register
Register for a free API key.

Request:
```json
{
  "name": "My AI Agent",
  "email": "agent@example.com",
  "accept_tos": true
}
```

### 5. POST /api/v1/agents/feedback
Report data quality (improves trust scores).

Request:
```json
{
  "provider_id": "YB-90123-CN",
  "feedback_type": "success",
  "message": "Contact info verified"
}
```

## Available Categories
  - aerospace/aircraft-parts (Aircraft Parts)
  - aerospace/avionics (Avionics)
  - aerospace/defense (Defense Equipment)
  - aerospace/drones (Drones & UAV)
  - aerospace/mro (MRO Services)
  - aerospace/space (Space Technology)
  - agriculture/beverages (Beverages)
  - agriculture/dairy (Dairy Products)
  - agriculture/equipment (Farm Equipment)
  - agriculture/fertilizers (Fertilizers)
  - agriculture/processing (Food Processing Equipment)
  - agriculture/fruits (Fruits & Vegetables)
  - agriculture/grains (Grains & Cereals)
  - agriculture/meat (Meat & Seafood)
  - agriculture/seeds (Seeds & Plants)
  - agriculture/spices (Spices & Herbs)
  - automotive/auto-electronics (Auto Electronics)
  - automotive/body (Body & Paint)
  - automotive/parts (Car Parts)
  - automotive/ev (Electric Vehicles)
  - automotive/lubricants (Lubricants)
  - automotive/motorcycles (Motorcycle Parts)
  - automotive/tires (Tires & Wheels)
  - automotive/trucks (Truck Parts)
  - beauty/cosmetics (Cosmetics & Makeup)
  - beauty/fragrances (Fragrances)
  - beauty/haircare (Haircare)
  - beauty/skincare (Skincare)
  - chemicals/adhesives (Adhesives & Sealants)
  - chemicals/industrial (Industrial Chemicals)
  - chemicals/paints (Paints & Coatings)
  - chemicals/plastics (Plastics & Polymers)
  - chemicals/rubber (Rubber Products)
  - chemicals/specialty (Specialty Chemicals)
  - construction/cement (Cement & Concrete)
  - construction/doors (Doors & Windows)
  - construction/heavy (Heavy Equipment)
  - construction/plumbing (Plumbing & HVAC)
  - construction/roofing (Roofing & Insulation)
  - construction/steel (Steel Structures)
  - construction/tiles (Tiles & Flooring)
  - construction/tools (Tools & Hardware)
  - education/edtech (EdTech & Software)
  - education/furniture-edu (School Furniture)
  - education/lab-edu (Science Labs)
  - education/sports-edu (Sports & Playground)
  - education/stationery (Stationery & Supplies)
  - electronics/connectors (Connectors & Cables)
  - electronics/consumer (Consumer Electronics)
  - electronics/displays (Displays & Screens)
  - electronics/led (LED & Lighting)
  - electronics/pcb (PCB & Assembly)
  - electronics/power (Power Supplies)
  - electronics/semiconductors (Semiconductors)
  - electronics/test (Test & Measurement)
  - energy/batteries (Batteries)
  - energy/battery-storage (Battery Storage)
  - energy/cables (Cables & Wiring)
  - energy/ev-chargers (EV Chargers)
  - energy/ev-charging (EV Charging)
  - energy/heat-pumps (Heat Pumps)
  - energy/hydrogen (Hydrogen)
  - energy/inverters (Inverters)
  - energy/mounting-systems (Mounting Systems)
  - energy/pv-modules (PV Modules)
  - energy/transformers (Transformers)
  - energy/wind (Wind Turbines)
  - environment/air (Air Treatment)
  - environment/recycling (Recycling Equipment)
  - environment/waste (Waste Management)
  - environment/water (Water Treatment)
  - finance/banking (Banking Technology)
  - finance/insurance (Insurance Technology)
  - finance/payment (Payment Solutions)
  - finance/trade (Trade Finance)
  - furniture/decor (Home Decor)
  - furniture/home (Home Furniture)
  - furniture/lighting (Home Lighting)
  - furniture/kitchen (Kitchen & Bathroom)
  - furniture/office (Office Furniture)
  - gifts/artificial (Artificial Flowers)
  - gifts/candles (Candles & Incense)
  - gifts/crafts (Handicrafts)
  - gifts/promotional (Promotional Items)
  - gifts/souvenirs (Souvenirs)
  - glass/ceramic-tiles (Ceramic Tiles)
  - glass/fiber-glass (Fiberglass)
  - glass/flat (Flat Glass)
  - glass/bottles-glass (Glass Bottles)
  - glass/tableware (Glassware & Tableware)
  - healthcare/dental (Dental)
  - healthcare/hospital (Hospital Furniture)
  - healthcare/lab (Lab Equipment)
  - healthcare/devices (Medical Devices)
  - healthcare/imaging (Medical Imaging)
  - healthcare/pharma (Pharmaceuticals)
  - healthcare/ppe (PPE & Disposables)
  - healthcare/rehab (Rehabilitation)
  - hospitality/buffet (Buffet & Serving)
  - hospitality/kitchen-comm (Commercial Kitchen)
  - hospitality/hotel (Hotel Equipment)
  - hospitality/laundry (Laundry Equipment)
  - hospitality/restaurant (Restaurant Furniture)
  - jewelry/costume (Costume Jewelry)
  - jewelry/diamonds (Diamonds & Gems)
  - jewelry/gold (Gold Jewelry)
  - jewelry/tools-jewelry (Jewelry Tools)
  - jewelry/silver (Silver Jewelry)
  - jewelry/watches (Watches)
  - machinery/boilers (Boilers & Furnaces)
  - machinery/generators (Generators)
  - machinery/hydraulics (Hydraulics)
  - machinery/pneumatics (Pneumatics)
  - manufacturing/3dprint (3D Printing)
  - manufacturing/bearings (Bearings & Seals)
  - manufacturing/cnc (CNC Machines)
  - manufacturing/compressors (Compressors & Pumps)
  - manufacturing/automation (Industrial Automation)
  - manufacturing/motors (Motors & Drives)
  - manufacturing/valves (Valves & Fittings)
  - manufacturing/welding (Welding)
  - marine/anchoring (Anchoring & Mooring)
  - marine/marine-engines (Marine Engines)
  - marine/navigation (Navigation Systems)
  - marine/offshore (Offshore Equipment)
  - marine/port (Port Equipment)
  - marine/ships (Ships & Boats)
  - medical/diagnostics (Diagnostics)
  - medical/beds (Hospital Beds)
  - medical/prosthetics (Prosthetics)
  - medical/surgical (Surgical Instruments)
  - metals/aluminum (Aluminum)
  - metals/copper (Copper & Brass)
  - metals/fabrication (Metal Fabrication)
  - metals/mining (Mining Equipment)
  - metals/stainless (Stainless Steel)
  - metals/steel (Steel Products)
  - mining/conveying (Conveying Systems)
  - mining/crushers (Crushers & Screens)
  - mining/explosives (Explosives & Blasting)
  - mining/minerals (Mineral Processing)
  - mining/drilling-mining (Mining Drills)
  - oilgas/drilling (Drilling Equipment)
  - oilgas/lpg (LPG & LNG)
  - oilgas/oilfield (Oilfield Services)
  - oilgas/petrochemicals (Petrochemicals)
  - oilgas/pipelines (Pipelines & Valves)
  - oilgas/refining (Refining Equipment)
  - packaging/bottles (Bottles & Containers)
  - packaging/corrugated (Corrugated Packaging)
  - packaging/flexible (Flexible Packaging)
  - packaging/labels (Labels & Tags)
  - packaging/machines (Packaging Machines)
  - packaging/paper (Paper Products)
  - pets/aquarium (Aquarium & Fish)
  - pets/grooming (Grooming Products)
  - pets/accessories (Pet Accessories)
  - pets/petfood (Pet Food)
  - pets/veterinary (Veterinary Equipment)
  - printing/ink (Ink & Toner)
  - printing/labels (Labels & Stickers)
  - printing/machines (Printing Machines)
  - printing/signage (Signage & Displays)
  - security/access (Access Control)
  - security/cctv (CCTV & Surveillance)
  - security/fire (Fire Safety)
  - security/safety (Safety Equipment)
  - sports/fitness (Fitness Equipment)
  - sports/outdoor (Outdoor & Camping)
  - sports/gear (Sports Gear)
  - sports/toys (Toys & Games)
  - technology/ai (AI & Machine Learning)
  - technology/ai-ml-platforms (AI & ML Platforms)
  - technology/cloud (Cloud & SaaS)
  - technology/cloud-services (Cloud Services)
  - technology/cybersecurity (Cybersecurity)
  - technology/erp (ERP & CRM)
  - technology/iot (IoT & Embedded)
  - technology/semiconductors (Semiconductors)
  - telecom/antennas (Antennas)
  - telecom/fiber (Fiber Optics)
  - telecom/network (Network Equipment)
  - telecom/software (Telecom Software)
  - test/magic (Magic & Fantasy)
  - test/rocks (Rocks & Minerals)
  - test/toys (Toys & Novelty)
  - textiles/fabrics (Fabrics & Textiles)
  - textiles/footwear (Footwear)
  - textiles/garments (Garments & Apparel)
  - textiles/leather (Leather Products)
  - textiles/machines (Textile Machinery)
  - textiles/yarn (Yarn & Thread)
  - transport/containers (Containers & Pallets)
  - transport/fleet (Fleet Management)
  - transport/freight (Freight & Shipping)
  - transport/warehousing (Warehousing)

## Query Parameters
- **category**: Category slug (required for /query)
- **country**: ISO 2-letter country code (e.g., "DE", "US", "CN")
- **role**: "manufacturer" | "dealer" | "distributor"
- **verified**: true/false — filter by verification status
- **sort**: "trust_desc" | "name_asc" | "country_asc" | "newest"
- **limit**: 1-25 (max 25 per query)
- **offset**: 0-500 (max 500)

## Authentication
Header: X-Agent-Key: ybot_your_api_key_here

## Rate Limits
- Free tier: 100 queries/hour, 1000 queries/day
- Verified tier: 500 queries/hour, 5000 queries/day
- Premium tier: 1000 queries/hour, 20000 queries/day

## Terms of Service
By using this API you agree to:
- No bulk extraction of the registry database
- No re-publishing data as a competing registry
- Attribution required when displaying YELLOW.bot data
- Violation results in immediate key revocation