322 lines
12 KiB
Markdown
322 lines
12 KiB
Markdown
# 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`
|