igny8/master-docs/20-api/ENDPOINTS/planner.md

Planner Endpoints

Purpose

Document planner API endpoints for keywords, clusters, and content ideas, including filters, bulk actions, and validation rules.

Code Locations (exact paths)

• Routing: backend/igny8_core/modules/planner/urls.py
• Views: backend/igny8_core/modules/planner/views.py
• Serializers: backend/igny8_core/modules/planner/serializers.py

High-Level Responsibilities

• CRUD for planner entities scoped by account/site/sector with search, filtering, ordering, and bulk operations.
• Enforce site/sector requirements and seed keyword alignment on creation.

Detailed Behavior

• Base path: /api/v1/planner/
• Viewsets (all inherit SiteSectorModelViewSet, scoped by account/site/sector, throttled with scope planner, paginated):
  • KeywordViewSet (/keywords/):
    • Search: seed_keyword__keyword.
    • Filters: status, cluster_id, seed_keyword intent/id; custom difficulty_min/max and volume_min/max (uses overrides or seed values).
    • Ordering: created_at, seed volume/difficulty.
    • Bulk: bulk_delete, bulk_update (status), bulk_add_from_seed (create Keywords from SeedKeywords after validating site/sector).
    • Create requires site_id and sector_id; validates site/sector existence and alignment.
  • ClusterViewSet (/clusters/):
    • Filters: status; standard CRUD; site/sector required on create.
  • ContentIdeasViewSet (/ideas/):
    • Filters: status, cluster; standard CRUD; site/sector required on create.
• Serializers enforce required fields on create (KeywordSerializer requires seed_keyword_id; site/sector write-only), expose read-only seed-derived fields and cluster/sector names.
• Error handling: unified responses; validation errors for missing site/sector/seed; bulk actions return 400 when IDs/status missing.

Data Structures / Models Involved (no code)

• Keywords, Clusters, ContentIdeas, SeedKeyword, plus Account, Site, Sector.

Execution Flow

• Requests → DRF auth → base viewset filters (account/site/sector) → serializer validation → model save → unified response; bulk actions operate on filtered queryset.

Cross-Module Interactions

• Feeds automation Stage 1–3 and writer tasks/content generation.
• Billing credits may be checked upstream when AI clustering/idea generation is invoked.

State Transitions

• Keywords: new → mapped; Clusters: new → mapped; ContentIdeas: new → queued → completed.

Error Handling

• Missing required IDs or validation failures return 400; unified 500 on unhandled errors.

Tenancy Rules

• All endpoints scoped to account/site/sector via base viewset; admin/developer/system roles can bypass filtering, but data retains tenant/site/sector fields.

Billing Rules

• No direct deductions in these endpoints; AI clustering/idea generation costs enforced where services are called.

Background Tasks / Schedulers

• None in planner endpoints; automation handles async flows.

Key Design Considerations

• Strict site/sector requirements prevent cross-site contamination.
• Seed linkage keeps keyword metadata consistent; overrides allow site-specific tuning.

How Developers Should Work With This Module

• Supply site_id/sector_id on create; use bulk actions for batch changes; extend filters/search/order as needed while respecting base scoping.