docs & ux improvmeents

2025-12-25 20:31:58 +00:00
parent 90e6e96b2b
commit 4bffede052
247 changed files with 6869 additions and 53517 deletions
--- a/docs/20-API/ENDPOINTS.md
+++ b/docs/20-API/ENDPOINTS.md
@@ -0,0 +1,266 @@
+# API Endpoints Reference
+
+**Last Verified:** December 25, 2025  
+**Base URL:** `/api/v1/`  
+**Documentation:** `/api/docs/` (Swagger) | `/api/redoc/` (ReDoc)
+
+---
+
+## Authentication
+
+All endpoints require authentication unless noted.
+
+**Methods:**
+- `Authorization: Bearer <jwt_token>` - JWT token
+- `Authorization: ApiKey <key>` - API key (WordPress integration)
+- Session cookie (Django Admin)
+
+---
+
+## Auth Endpoints (`/api/v1/auth/`)
+
+| Method | Path | Handler | Auth | Purpose |
+|--------|------|---------|------|---------|
+| POST | `/register/` | `RegisterView` | ❌ | Create account |
+| POST | `/login/` | `LoginView` | ❌ | Get tokens |
+| POST | `/logout/` | `LogoutView` | ✅ | Invalidate session |
+| POST | `/token/refresh/` | `RefreshTokenView` | ✅ | Refresh access token |
+| POST | `/password/change/` | `ChangePasswordView` | ✅ | Change password |
+| POST | `/password/reset/` | `RequestPasswordResetView` | ❌ | Request reset email |
+| POST | `/password/reset/confirm/` | `ResetPasswordView` | ❌ | Confirm reset |
+| GET | `/groups/` | `RoleViewSet.list` | ✅ | List roles |
+| GET | `/users/` | `UserViewSet.list` | ✅ | List users |
+| POST | `/users/` | `UserViewSet.create` | ✅ | Create user |
+| GET | `/account/` | `AccountViewSet.retrieve` | ✅ | Get account |
+| PUT | `/account/` | `AccountViewSet.update` | ✅ | Update account |
+| GET | `/sites/` | `SiteViewSet.list` | ✅ | List sites |
+| POST | `/sites/` | `SiteViewSet.create` | ✅ | Create site |
+| 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 |
+
+---
+
+## Planner Endpoints (`/api/v1/planner/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/keywords/` | `KeywordViewSet.list` | List keywords |
+| POST | `/keywords/` | `KeywordViewSet.create` | Create keyword |
+| GET | `/keywords/{id}/` | `KeywordViewSet.retrieve` | Get keyword |
+| PUT | `/keywords/{id}/` | `KeywordViewSet.update` | Update keyword |
+| DELETE | `/keywords/{id}/` | `KeywordViewSet.destroy` | Delete keyword |
+| POST | `/keywords/bulk_delete/` | `KeywordViewSet.bulk_delete` | Hard delete multiple |
+| POST | `/keywords/bulk_status/` | `KeywordViewSet.bulk_status` | Update status |
+| POST | `/keywords/add_to_workflow/` | `KeywordViewSet.add_to_workflow` | Add seed keywords |
+| GET | `/clusters/` | `ClusterViewSet.list` | List clusters |
+| POST | `/clusters/` | `ClusterViewSet.create` | Create cluster |
+| POST | `/clusters/auto_cluster/` | `ClusterViewSet.auto_cluster` | AI clustering |
+| POST | `/clusters/generate_ideas/` | `ClusterViewSet.generate_ideas` | Generate ideas |
+| GET | `/ideas/` | `ContentIdeaViewSet.list` | List ideas |
+| POST | `/ideas/` | `ContentIdeaViewSet.create` | Create idea |
+| POST | `/ideas/create_tasks/` | `ContentIdeaViewSet.create_tasks` | Convert to tasks |
+
+**Query Parameters:**
+- `?site_id=` - Filter by site
+- `?sector_id=` - Filter by sector
+- `?status=` - Filter by status
+- `?cluster_id=` - Filter by cluster
+- `?difficulty_min=`, `?difficulty_max=` - Difficulty range
+- `?volume_min=`, `?volume_max=` - Volume range
+
+---
+
+## Writer Endpoints (`/api/v1/writer/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/tasks/` | `TaskViewSet.list` | List tasks |
+| POST | `/tasks/` | `TaskViewSet.create` | Create task |
+| POST | `/tasks/bulk_create/` | `TaskViewSet.bulk_create` | Create multiple |
+| POST | `/tasks/{id}/generate_content/` | `TaskViewSet.generate_content` | AI generation |
+| GET | `/content/` | `ContentViewSet.list` | List content |
+| POST | `/content/` | `ContentViewSet.create` | Create content |
+| GET | `/content/{id}/` | `ContentViewSet.retrieve` | Get content |
+| PUT | `/content/{id}/` | `ContentViewSet.update` | Update content |
+| POST | `/content/{id}/update_content/` | `ContentViewSet.update_content` | Update with validation |
+| POST | `/content/{id}/generate_images/` | `ContentViewSet.generate_images` | Generate images |
+| POST | `/content/{id}/publish_to_wordpress/` | `ContentViewSet.publish_to_wordpress` | Publish to WP |
+| GET | `/images/` | `ImageViewSet.list` | List images |
+| POST | `/images/generate_for_content/` | `ImageViewSet.generate_for_content` | Generate images |
+| POST | `/images/regenerate/` | `ImageViewSet.regenerate` | Regenerate image |
+| GET | `/taxonomies/` | `TaxonomyViewSet.list` | List taxonomies |
+
+---
+
+## Billing Endpoints (`/api/v1/billing/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/balance/` | `CreditBalanceViewSet.list` | Current balance |
+| GET | `/usage/` | `CreditUsageViewSet.list` | Usage log |
+| GET | `/usage/summary/` | `CreditUsageViewSet.summary` | Usage summary |
+| GET | `/usage/limits/` | `CreditUsageViewSet.limits` | Plan limits |
+| GET | `/transactions/` | `TransactionViewSet.list` | Transaction history |
+
+---
+
+## Integration Endpoints (`/api/v1/integration/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/` | `SiteIntegrationViewSet.list` | List integrations |
+| POST | `/` | `SiteIntegrationViewSet.create` | Create integration |
+| PUT | `/{id}/` | `SiteIntegrationViewSet.update` | Update integration |
+| DELETE | `/{id}/` | `SiteIntegrationViewSet.destroy` | Delete integration |
+| POST | `/{id}/test_connection/` | Test connection | Verify credentials |
+| POST | `/{id}/test_collection_connection/` | Test collection | Test specific type |
+| POST | `/{id}/sync/` | Trigger sync | Start sync |
+| GET | `/{id}/sync_status/` | Sync status | Current progress |
+| POST | `/{id}/update_structure/` | Update structure | Refresh site data |
+| GET | `/{id}/content_types/` | Content types | Available types |
+| GET | `/{id}/sync_health/` | Sync health | Statistics |
+| POST | `/site_sync/` | Site-level sync | Sync by site ID |
+| POST | `/webhook/wordpress/` | WordPress webhook | Receive WP updates |
+
+---
+
+## System Endpoints (`/api/v1/system/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/settings/integrations/openai/` | Get OpenAI settings | Current config |
+| PUT | `/settings/integrations/openai/` | Save OpenAI settings | Update config |
+| GET | `/settings/integrations/image_generation/` | Get image settings | Current config |
+| PUT | `/settings/integrations/image_generation/` | Save image settings | Update config |
+| POST | `/settings/integrations/test/` | Test connection | Verify API keys |
+| GET | `/prompts/` | List prompts | All prompts |
+| GET | `/prompts/{type}/` | Get prompt | Specific prompt |
+| PUT | `/prompts/{type}/` | Save prompt | Update prompt |
+| POST | `/prompts/{type}/reset/` | Reset prompt | Reset to default |
+| GET | `/modules/` | Get modules | Module enable state |
+| PUT | `/modules/` | Save modules | Update enabled |
+| GET | `/health/` | Health check | System status |
+
+---
+
+## Automation Endpoints (`/api/v1/automation/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/config/` | Get config | Automation config |
+| PUT | `/update_config/` | Update config | Save settings |
+| POST | `/run_now/` | Run now | Start manual run |
+| GET | `/current_run/` | Current run | Run status |
+| GET | `/pipeline_overview/` | Pipeline | Stage counts |
+| GET | `/current_processing/` | Processing | Live status |
+| POST | `/pause/` | Pause | Pause run |
+| POST | `/resume/` | Resume | Resume run |
+| POST | `/cancel/` | Cancel | Cancel run |
+| GET | `/history/` | History | Past runs |
+| GET | `/logs/` | Logs | Activity log |
+| GET | `/estimate/` | Estimate | Credit estimate |
+
+**Query Parameters:** All require `?site_id=`, run-specific require `?run_id=`
+
+---
+
+## Linker Endpoints (`/api/v1/linker/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| POST | `/process/` | `LinkerViewSet.process` | Process single content |
+| POST | `/batch_process/` | `LinkerViewSet.batch_process` | Process multiple |
+
+---
+
+## Optimizer Endpoints (`/api/v1/optimizer/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| POST | `/optimize/` | `OptimizerViewSet.optimize` | Optimize content |
+| POST | `/batch_optimize/` | `OptimizerViewSet.batch_optimize` | Batch optimize |
+| POST | `/analyze/` | `OptimizerViewSet.analyze` | Analyze only |
+
+---
+
+## Publisher Endpoints (`/api/v1/publisher/`)
+
+| Method | Path | Handler | Purpose |
+|--------|------|---------|---------|
+| GET | `/records/` | `PublishingRecordViewSet.list` | List records |
+| POST | `/records/` | `PublishingRecordViewSet.create` | Create record |
+| GET | `/deployments/` | `DeploymentViewSet.list` | List deployments |
+| POST | `/publish/` | `PublishContentViewSet.publish` | Publish content |
+| GET | `/publish/status/` | `PublishContentViewSet.status` | Publish status |
+| GET | `/site-definition/` | `SiteDefinitionViewSet.list` | Public site def |
+
+---
+
+## Response Format
+
+### Success Response
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "message": "Optional message"
+}
+```
+
+### Error Response
+
+```json
+{
+  "success": false,
+  "error": "Error message",
+  "code": "ERROR_CODE"
+}
+```
+
+### Paginated Response
+
+```json
+{
+  "count": 100,
+  "next": "http://api.igny8.com/api/v1/planner/keywords/?page=2",
+  "previous": null,
+  "results": [ ... ]
+}
+```
+
+---
+
+## HTTP Status Codes
+
+| Code | Meaning |
+|------|---------|
+| 200 | Success |
+| 201 | Created |
+| 400 | Bad Request |
+| 401 | Unauthorized |
+| 402 | Payment Required (insufficient credits) |
+| 403 | Forbidden |
+| 404 | Not Found |
+| 429 | Rate Limited |
+| 500 | Server Error |
+
+---
+
+## Rate Limiting
+
+Rate limits are scoped by operation type:
+
+| Scope | Limit |
+|-------|-------|
+| AI operations | 60/min |
+| Content operations | 100/min |
+| Auth operations | 20/min |
+| General | 300/min |
+
+Rate limit headers included in responses:
+- `X-RateLimit-Limit`
+- `X-RateLimit-Remaining`
+- `X-RateLimit-Reset`