igny8/docs/90-ARCHIVED/master-docs-original/20-api/REST-API-REFERENCE.md

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.