igny8/docs/20-API/ENDPOINTS.md

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

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