igny8/docs/20-API/ENDPOINTS.md

API Endpoints Reference

Last Verified: January 3, 2026
Version: 1.3.2
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
POST	/content/{id}/schedule/	ContentViewSet.schedule	Schedule for publishing (v1.3.2)
POST	/content/{id}/unschedule/	ContentViewSet.unschedule	Remove from schedule (v1.3.2)
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

Content Query Parameters (v1.3.2):

• ?status__in=draft,review,approved - Filter by multiple workflow statuses
• ?site_status=scheduled - Filter by publishing status
• ?site_id= - Filter by site

Schedule Endpoint Request:

POST /api/v1/writer/content/{id}/schedule/
{
  "scheduled_publish_at": "2026-01-15T09:00:00Z"
}

Schedule Endpoint Response:

{
  "content_id": 123,
  "site_status": "scheduled",
  "scheduled_publish_at": "2026-01-15T09:00:00Z"
}

---

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

Publishing Settings Endpoints (v1.3.2)

Method	Path	Handler	Purpose
GET	/sites/{site_id}/publishing-settings/	PublishingSettingsViewSet.retrieve	Get publishing settings
PUT	/sites/{site_id}/publishing-settings/	PublishingSettingsViewSet.update	Update settings (full)
PATCH	/sites/{site_id}/publishing-settings/	PublishingSettingsViewSet.partial_update	Update settings (partial)

Publishing Settings Response:

{
  "id": 1,
  "site": 5,
  "auto_approval_enabled": true,
  "auto_publish_enabled": true,
  "daily_publish_limit": 3,
  "weekly_publish_limit": 15,
  "monthly_publish_limit": 50,
  "publish_days": ["mon", "tue", "wed", "thu", "fri"],
  "publish_time_slots": ["09:00", "14:00", "18:00"],
  "created_at": "2026-01-03T10:00:00Z",
  "updated_at": "2026-01-03T10:00:00Z"
}

---

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:

{
  "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

{
  "success": true,
  "data": { ... },
  "message": "Optional message"
}

Error Response

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

Paginated Response

{
  "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