docs re-org

docs/20-API/API-REFERENCE.md

@@ -0,0 +1,73 @@
+# REST API Reference
+
+## Purpose
+Summarize the major API groups, their base paths, and key actions as implemented in routing and viewsets.
+
+## Code Locations (exact paths)
+- Root routing: `backend/igny8_core/urls.py`
+- Auth endpoints: `backend/igny8_core/auth/urls.py` (APIView + routers)
+- Account management: `backend/igny8_core/api/urls.py`
+- Planner: `backend/igny8_core/modules/planner/urls.py`
+- Writer: `backend/igny8_core/modules/writer/urls.py`
+- System: `backend/igny8_core/modules/system/urls.py`
+- Billing: `backend/igny8_core/business/billing/urls.py`, `backend/igny8_core/modules/billing/urls.py`
+- Automation: `backend/igny8_core/business/automation/urls.py`
+- Integration: `backend/igny8_core/modules/integration/urls.py`
+- Linker/Optimizer/Publisher: respective `modules/*/urls.py`
+
+## High-Level Responsibilities
+- Provide RESTful CRUD endpoints for core resources (auth, planner, writer, billing, automation, integration, etc.) plus custom actions for domain workflows (automation run, billing payments, integration sync, content generation).
+
+## Detailed Behavior (by group)
+- Authentication (`/api/v1/auth/`):
+  - Routers: groups, users, accounts, subscriptions, site-access, plans, sites, sectors, industries, seed-keywords.
+  - APIViews: register, login, change password, refresh token; responses issue JWTs and session login.
+  - CSV admin helpers exposed separately under `/admin/igny8_core_auth/...` for industries/seed keywords.
+- Account management (`/api/v1/account/`):
+  - Settings (`settings/` get/patch), team (`team/` list/create, `team/<id>/` delete), usage analytics (`usage/analytics/`).
+- Planner (`/api/v1/planner/`):
+  - `keywords/`, `clusters/`, `ideas/` (CRUD, filtering/search/ordering, bulk delete/update, bulk add from seed).
+- Writer (`/api/v1/writer/`):
+  - `tasks/`, `images/`, `content/`, `taxonomies/` (CRUD, filtering/search/ordering).
+  - Custom actions: `tasks/auto_generate_content` (AI generation), `tasks/bulk_*`, `images/file`, grouped image utilities; content/taxonomy helpers in viewset.
+- System (`/api/v1/system/`): system settings, prompts, author profiles, etc. (see module docs).
+- Billing (`/api/v1/billing/`):
+  - Invoices (`invoices/`, detail, `download_pdf`), payments (`payments/`, `available_methods`, manual payment), credit packages (`credit-packages/`, purchase), transactions (`transactions/`), payment methods (`payment-methods/`, `set_default`), credits (`credits/balance`, `credits/usage`, `credits/transactions`).
+  - Admin billing under `/api/v1/admin/` (see module billing admin URLs).
+- Automation (`/api/v1/automation/`):
+  - Config (`config`, `update_config`), run (`run_now`), current run, history, logs, estimate, pipeline_overview, current_processing, pause/resume/cancel.
+- Integration (`/api/v1/integration/`):
+  - `integrations/` CRUD, `test_connection`, collection-level `test-connection`, `sync`, `sync_status`, `update-structure`, `get_content_types`, `debug_status`, `sync_wordpress_content`.
+  - Webhooks: `/webhooks/wordpress/status/`, `/webhooks/wordpress/metadata/`.
+- Linker/Optimizer/Publisher: endpoints under `/api/v1/linker/`, `/api/v1/optimizer/`, `/api/v1/publisher/` (viewsets for respective domain resources; see module docs).
+
+## Data Structures / Models Involved (no code)
+- Auth/account models, planner models (Keywords/Clusters/ContentIdeas), writer models (Tasks/Content/Images/Taxonomy), billing models (invoices/payments/credits), automation models (runs/configs), integration models (SiteIntegration/SyncEvent), and other module models as routed above.
+
+## Execution Flow
+- Requests hit module routers; viewsets/actions enforce permissions, throttles, and tenancy; serializers map models; responses use unified format.
+
+## Cross-Module Interactions
+- Auth JWTs used by all modules.
+- Billing credits checked in writer/automation flows; billing endpoints expose balances/usage.
+- Integration and publishing rely on writer content; automation depends on planner/writer data.
+
+## State Transitions
+- Managed by respective viewsets (e.g., task status, automation status, invoice/payment status).
+
+## Error Handling
+- Unified error responses; 4xx/5xx codes per viewset logic; throttling per scope.
+
+## Tenancy Rules
+- Base viewsets enforce account/site/sector filtering; API key auth supports WordPress paths; admin/developer/system roles may bypass filters as coded in base viewsets/auth middleware.
+
+## Billing Rules
+- Credits enforced in writer/automation service calls; billing endpoints expose ledger/usage/balance; insufficient credits return 402 where applicable.
+
+## Background Tasks / Schedulers
+- Automation actions enqueue Celery runs; writer content generation may enqueue AI tasks; other modules mostly synchronous.
+
+## Key Design Considerations
+- Consistent `/api/v1/` namespace with per-module routers.
+- OpenAPI schema available at `/api/schema`, Swagger at `/api/docs`, Redoc at `/api/redoc`.
+- Use module docs for endpoint-level details; this file outlines the map of API groups and actions.