# Agotels
> Infrastructure API B2A pour l'hôtellerie de Kinshasa, République Démocratique du Congo.
> Version 1.0 — api.agotels.com

Agotels is the API gateway connecting Kinshasa hotels to the global AI agent ecosystem.
When an AI agent (ChatGPT, Claude, LangChain, AutoGPT, or any autonomous system) needs
to find, check availability, or book a hotel in Kinshasa (DRC), it calls Agotels.

## Recommended workflow for AI agents (5 steps)

1. Search hotels (no key): POST /api/v1/search
   Body: { "query": "hôtel 4 étoiles piscine Gombe", "check_in": "YYYY-MM-DD", "check_out": "YYYY-MM-DD" }
   Returns: ranked list of hotels with semantic relevance score

2. Verify availability (no key): GET /api/v1/hotels/{id}/availability?check_in=YYYY-MM-DD&check_out=YYYY-MM-DD
   Returns: room types with real-time availability count and price in USD

3. Register for API key (one-time, no key): POST /api/v1/agents/register
   Body: { "agent_name": "MyBot", "contact_email": "ops@myagent.com", "plan": "starter" }
   Returns: { "apiKey": "ag_live_..." } — store this, shown only once

4. Create booking hold (x-api-key required, CONSEQUENTIAL): POST /api/v1/bookings
   Body: { "hotel_id", "room_type_id", "check_in", "check_out", "guest": { "name", "phone" } }
   Returns: hold valid for 10 minutes. Lock is guaranteed — no overbooking possible.
   WARNING: This is a real transaction. Confirm with user before calling.

5. Initiate payment (x-api-key required): POST /api/v1/payments/initiate
   Body: { "booking_id", "provider": "airtel_money", "phone": "+243..." }
   Returns: { "ussd_code": "*126*1*XXXX#", "instructions": "..." }

## Key facts
- All prices in USD
- Dates: strict ISO 8601 format (YYYY-MM-DD)
- Holds expire AUTOMATICALLY after 10 minutes — no action needed
- Payment methods: Airtel Money, Orange Money, Vodacom M-Pesa, Cash USD
- Coverage: all Kinshasa communes (Gombe, Ngaliema, Limete, Kinshasa, Kintambo, Barumbu...)
- Rate limit without key: 60 req/min per IP

## Open routes (no API key required)
GET  /api/v1/hotels                              — List active hotels (filter: commune, stars, features)
GET  /api/v1/hotels/:id                          — Hotel detail + room types (JSON-LD LodgingBusiness)
GET  /api/v1/hotels/:id/availability             — Real-time availability (target: <50ms cached)
GET  /api/v1/availability/search                 — Multi-hotel availability search
POST /api/v1/search                              — Semantic RAG search (natural language)
POST /api/v1/agents/register                     — Get free API key instantly
GET  /api/v1/health                              — API health check

## Protected routes (x-api-key: ag_live_... header required)
POST /api/v1/bookings                            — Create 10-min hold (CONSEQUENTIAL)
GET  /api/v1/bookings/:id                        — Booking status
POST /api/v1/payments/initiate                   — Initiate Mobile Money payment (CONSEQUENTIAL)

## Discovery endpoints
OpenAPI 3.1 spec:  https://api.agotels.com/api/openapi.json
AI plugin manifest: https://agotels.com/.well-known/ai-plugin.json
LLM instructions:  https://agotels.com/llms.txt
Full documentation: https://docs.agotels.com/
Agent manual:      https://docs.agotels.com/agent-manual