# 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.