Version 1.8.2

2026-01-18 22:14:34 +00:00
parent 328098a48c
commit e57c4bf1ac
4 changed files with 447 additions and 10 deletions
--- a/docs/20-API/ENDPOINTS.md
+++ b/docs/20-API/ENDPOINTS.md
@@ -1,7 +1,7 @@
 # API Endpoints Reference

-**Last Verified:** January 18, 2026  
-**Version:** 1.8.1  
+**Last Verified:** January 19, 2026  
+**Version:** 1.8.2  
 **Base URL:** `/api/v1/`  
 **Documentation:** `/api/docs/` (Swagger) | `/api/redoc/` (ReDoc)

@@ -39,7 +39,116 @@ All endpoints require authentication unless noted.
 | GET | `/sectors/` | `SectorViewSet.list` | ✅ | List sectors |
 | POST | `/sectors/` | `SectorViewSet.create` | ✅ | Create sector |
 | GET | `/industries/` | `IndustryViewSet.list` | ✅ | List industries |
-| GET | `/seed-keywords/` | `SeedKeywordViewSet.list` | ✅ | List seed keywords |
+| GET | `/keywords-library/` | `SeedKeywordViewSet.list` | ✅ | List keywords library (v1.8.2) |
+| GET | `/keywords-library/sector_stats/` | `SeedKeywordViewSet.sector_stats` | ✅ | Get sector statistics (v1.8.2) |
+
+---
+
+## Keywords Library Endpoints (v1.8.2)
+
+**New Endpoint:** `/api/v1/keywords-library/`  
+**Previous:** `/api/v1/auth/seed-keywords/` (deprecated, no backward compatibility)
+
+### List Keywords
+
+```
+GET /api/v1/keywords-library/
+```
+
+**Query Parameters:**
+- `sector_ids` _(string, comma-separated)_ - Filter by specific sector IDs (e.g., `1,2,3`)
+  - **New in v1.8.2:** Ensures sites only see keywords from their configured sectors
+- `search` _(string)_ - Search keyword names
+- `country` _(string)_ - Filter by country code (e.g., `US`, `UK`)
+- `volume_min` _(number)_ - Minimum search volume
+- `volume_max` _(number)_ - Maximum search volume
+- `difficulty` _(string)_ - SEO difficulty level (`easy`, `medium`, `hard`, `very_hard`)
+- `is_high_opportunity` _(boolean)_ - Filter high-opportunity keywords
+- `is_paid` _(boolean)_ - Filter paid/premium keywords
+- `ordering` _(string)_ - Sort field (prefix `-` for descending)
+  - Options: `keyword`, `volume`, `difficulty`, `country`
+  - Default: `-volume`
+- `page` _(number)_ - Page number for pagination
+- `page_size` _(number)_ - Results per page (default: 20)
+
+**Example Request:**
+```bash
+GET /api/v1/keywords-library/?sector_ids=1,2,3&country=US&difficulty=easy&ordering=-volume&page=1
+```
+
+**Response:**
+```json
+{
+  "count": 150,
+  "next": "http://api.igny8.com/api/v1/keywords-library/?page=2&sector_ids=1,2,3",
+  "previous": null,
+  "results": [
+    {
+      "id": 1,
+      "keyword": "cloud computing services",
+      "volume": 12000,
+      "difficulty": "medium",
+      "country": "US",
+      "industry_sector": 1,
+      "industry_sector_name": "Cloud Infrastructure & Services",
+      "is_high_opportunity": true,
+      "is_paid": false,
+      "credit_cost": 0,
+      "created_at": "2025-01-15T10:00:00Z"
+    }
+  ]
+}
+```
+
+### Sector Statistics
+
+```
+GET /api/v1/keywords-library/sector_stats/
+```
+
+Returns aggregated statistics per sector for the keywords library.
+
+**Query Parameters:**
+- `sector_ids` _(string, comma-separated)_ - Filter by specific sector IDs
+  - **New in v1.8.2:** Returns stats only for specified sectors
+
+**Example Request:**
+```bash
+GET /api/v1/keywords-library/sector_stats/?sector_ids=1,2,3
+```
+
+**Response:**
+```json
+[
+  {
+    "sector_id": 1,
+    "sector_name": "Cloud Infrastructure & Services",
+    "sector_description": "Keywords related to cloud computing, hosting, and infrastructure services",
+    "stats": {
+      "total": 250,
+      "added": 45,
+      "available": 205,
+      "high_opportunity": 80,
+      "paid": 30,
+      "free": 220
+    }
+  }
+]
+```
+
+**Stat Definitions:**
+- `total` - All keywords in sector
+- `added` - Keywords site has added to their workflow
+- `available` - Keywords not yet added (total - added)
+- `high_opportunity` - Premium keywords with high volume and potential
+- `paid` - Premium keywords requiring credits
+- `free` - Keywords with no credit cost
+
+**Use Cases:**
+1. **Sector Metric Cards** - Display stats per sector with clickable filters
+2. **Smart Suggestions** - Show available counts for bulk-add operations
+3. **Progress Tracking** - Track keyword adoption across sectors
+4. **Budget Planning** - Understand credit requirements for paid keywords

 ---