system-prompts-and-models-of-ai-tools/dealix/docs/archive/api_md_DEPRECATED.md

API Reference

Interactive Swagger UI: http://localhost:8000/docs ReDoc: http://localhost:8000/redoc OpenAPI JSON: http://localhost:8000/openapi.json

---

Authentication

The current version ships without auth on the public API — add your own layer (API key header, JWT, OAuth) behind a reverse proxy for production.

Recommended: use a simple API key via middleware, or Cloudflare Access / Auth0 in front.

---

Endpoints

Root & Health

Method	Path	Description
GET	/	Service info
GET	/health	Full health including configured LLM providers
GET	/ready	Readiness probe
GET	/live	Liveness probe

---

Leads (Phase 8)

POST /api/v1/leads

Run a lead through the full acquisition pipeline.

Request (LeadCreateRequest):

{
  "company": "شركة التقنية المتقدمة",
  "name": "أحمد محمد",
  "email": "ahmed@example.sa",
  "phone": "+966501234567",
  "sector": "technology",
  "company_size": "medium",
  "region": "Saudi Arabia",
  "budget": 50000,
  "message": "نحتاج نظام AI لإدارة المبيعات",
  "source": "website"
}

Query parameters:

• auto_book: bool = true
• auto_proposal: bool = false

Response (PipelineResponse):

{
  "lead": { "id": "lead_...", "fit_score": 0.82, "status": "qualified", ... },
  "fit_score": { "overall_score": 0.82, "tier": "A", "reasons": [...], ... },
  "extraction": { "pain_points": [...], "urgency_score": 0.7, ... },
  "qualification": { "questions": [...], "bant_score": 0.5, ... },
  "crm_sync": { "synced": true, "contact_id": "...", "deal_id": "..." },
  "booking": { "provider": "calendly", "link": "https://calendly.com/...", ... },
  "proposal": null,
  "warnings": []
}

---

Sales

POST /api/v1/sales/script

Get a bilingual sales script.

Request (SalesScriptRequest):

{
  "sector": "technology",
  "locale": "ar",
  "script_type": "opener",
  "name": "أحمد",
  "company": "شركتكم"
}

Script types: opener, follow_up_1, follow_up_2, demo_confirm, proposal_cover.

POST /api/v1/sales/proposal

Generate a one-off proposal (outside the pipeline).

---

Sectors (Phase 9)

GET /api/v1/sectors/{sector}

Deep intel for a single Saudi sector.

Path: sector — one of: technology, real_estate, healthcare, education, logistics, retail, finance, manufacturing, consulting, construction, oil_gas, tourism.

Query: enrich_with_llm=true to add live LLM research on top of baseline.

GET /api/v1/sectors/best/opportunity

Returns the sector with the highest growth_rate × ai_readiness.

GET /api/v1/sectors/target/list

Top 5 target sectors.

POST /api/v1/sectors/content

Generate a content piece for a sector topic.

Request:

{
  "topic": "أفضل 3 استخدامات AI في قطاع الصحة السعودي",
  "content_type": "article",
  "channel": "blog",
  "locale": "ar",
  "length": 800
}

---

Agents (direct execution, useful for testing)

Method	Path	Description
POST	/api/v1/agents/intake	Run just the Intake agent
POST	/api/v1/agents/pain-extractor	Run just the Pain extractor
POST	/api/v1/agents/icp-match	Run Intake + ICP
POST	/api/v1/agents/research	Run a market research question

---

Webhooks

GET / POST /api/v1/webhooks/whatsapp

Meta WhatsApp Cloud API webhook.

• GET: verification handshake (requires hub.mode, hub.verify_token, hub.challenge)
• POST: incoming messages — auto-routed through the acquisition pipeline

Verifies X-Hub-Signature-256 HMAC if WHATSAPP_APP_SECRET is configured.

POST /api/v1/webhooks/calendly

Calendly event lifecycle notifications.

POST /api/v1/webhooks/hubspot

HubSpot subscription events.

---

Error format

All AICompanyError subclasses map to 400:

{
  "error": "IntegrationError",
  "detail": "HUBSPOT_ACCESS_TOKEN not configured"
}

Validation errors return 422 with FastAPI's default format.

---

Rate limiting

Not enabled by default. Recommended: slowapi middleware or an upstream proxy (nginx, Cloudflare).

---

cURL examples

# Submit a lead
curl -X POST http://localhost:8000/api/v1/leads \
  -H "Content-Type: application/json" \
  -d @examples/lead_payload.json

# Get Arabic opener script
curl -X POST http://localhost:8000/api/v1/sales/script \
  -H "Content-Type: application/json" \
  -d '{"sector":"healthcare","locale":"ar","script_type":"opener","name":"د. أحمد"}'

# Get healthcare sector intel with LLM enrichment
curl 'http://localhost:8000/api/v1/sectors/healthcare?enrich_with_llm=true'

# Best opportunity
curl http://localhost:8000/api/v1/sectors/best/opportunity