# API Endpoints Reference

**Last Verified:** December 27, 2025  
**Version:** 1.2.0  
**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 | `/settings/content/{key}/` | `ContentSettingsViewSet.retrieve` | Get content settings |
| POST | `/settings/content/{key}/save/` | `ContentSettingsViewSet.save_settings` | Save content settings |
| 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 |

**Content Settings Keys:**
- `content_generation` - AI writing settings (default_article_length, default_tone, include_faq, enable_internal_linking, etc.)
- `publishing` - Publishing defaults (default_publish_status, auto_schedule, schedule_frequency, schedule_times)

---

## Notification Endpoints (`/api/v1/notifications/`) - v1.2.0

| Method | Path | Handler | Purpose |
|--------|------|---------|---------|
| GET | `/` | `NotificationViewSet.list` | List notifications (paginated) |
| GET | `/{id}/` | `NotificationViewSet.retrieve` | Get notification detail |
| DELETE | `/{id}/` | `NotificationViewSet.destroy` | Delete notification |
| POST | `/{id}/read/` | `NotificationViewSet.read` | Mark single notification as read |
| POST | `/read-all/` | `NotificationViewSet.read_all` | Mark all notifications as read |
| GET | `/unread-count/` | `NotificationViewSet.unread_count` | Get unread notification count |

**Query Parameters:**
- `?page=` - Page number for pagination
- `?page_size=` - Results per page (default 20)
- `?is_read=` - Filter by read status (true/false)
- `?notification_type=` - Filter by type (ai_task, system, credit, billing, integration, content, info)

**Notification Types:**
- `ai_cluster_complete`, `ai_cluster_failed` - Clustering operations
- `ai_ideas_complete`, `ai_ideas_failed` - Idea generation
- `ai_content_complete`, `ai_content_failed` - Content generation
- `ai_images_complete`, `ai_images_failed` - Image generation
- `ai_prompts_complete`, `ai_prompts_failed` - Image prompt generation
- `content_ready_review`, `content_published`, `content_publish_failed` - Workflow
- `wordpress_sync_success`, `wordpress_sync_failed` - WordPress sync
- `credits_low`, `credits_depleted` - Billing alerts
- `site_setup_complete`, `keywords_imported` - Setup
- `system_info` - System notifications

**Response Format:**
```json
{
  "id": 1,
  "notification_type": "ai_content_complete",
  "severity": "success",
  "title": "Content Generated",
  "message": "Generated 5 articles successfully",
  "is_read": false,
  "created_at": "2025-12-27T12:00:00Z",
  "read_at": null,
  "action_label": "View Content",
  "action_url": "/writer/content",
  "metadata": {"count": 5, "credits": 250}
}
```

---

## 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`