API Reference
Relevant source files
The following files were used as context for generating this wiki page:
ALwrity provides a robust, modular RESTful API architecture built on FastAPI to support AI-powered content creation, strategic planning, and digital marketing automation. The API acts as the central orchestration layer, connecting the React frontend with multiple AI providers (OpenAI, Gemini, Anthropic) and specialized backend services for SEO, social media, and research.
The system is organized into functional domains, including onboarding, content planning, and platform-specific content generation (LinkedIn, Facebook). It features automated OpenAPI/Swagger documentation, standardized JSON response formats, and comprehensive health monitoring across all modules.
Sources: README.md, backend/README.md, SETUP_GUIDE.md
Core Backend Architecture
The backend follows a modular service-oriented architecture where API endpoints (routers) are separated from business logic (services) and data structures (models). This separation ensures maintainability and allows for independent scaling of specific features like AI strategy generation or social media writing.
The architecture leverages FastAPI for high-performance asynchronous operations, supporting concurrent AI service requests.
Sources: backend/api/content_planning/README.md, backend/README.md
Onboarding and Configuration API
The Onboarding API manages the initial setup for users, including API key configuration for LLM providers and website analysis. It uses a step-based progression system to ensure all necessary parameters are configured before content generation begins.
Onboarding Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/onboarding/status | GET | Retrieves current onboarding status and completion state. |
/api/onboarding/step/{n} | GET | Returns data for a specific onboarding step (1-6). |
/api/onboarding/step/{n}/complete | POST | Marks a step as complete and saves associated data. |
/api/onboarding/api-keys | POST | Saves and validates AI provider API keys. |
/api/onboarding/providers/{p}/validate | POST | Validates a specific provider's key (e.g., OpenAI, Gemini). |
Sources: SETUP_GUIDE.md, backend/README.md
Content Planning API
The Content Planning module is the strategic core of ALwrity, providing endpoints for AI-powered strategy generation, gap analysis, and automated calendar creation. It is organized into several sub-routers: strategies, calendar_events, gap_analysis, and ai_analytics.
The sequence above illustrates the workflow for generating a new AI-driven content strategy.
Sources: backend/api/content_planning/README.md, backend/api/content_planning/services/content_strategy/README.md
Strategic Endpoints
| Category | Endpoint | Method | Key Parameters |
|---|---|---|---|
| Strategies | /strategies/ | POST | user_id, name, industry, target_audience |
| Gap Analysis | /gap-analysis/analyze | POST | website_url, competitor_urls, target_keywords |
| Analytics | /ai-analytics/content-evolution | POST | strategy_id, time_period |
| Calendar | /calendar-generation/generate-calendar | POST | strategy_id, calendar_type (weekly/monthly) |
Sources: backend/api/content_planning/README.md
Social Media Content Generation
ALwrity provides specialized APIs for platform-specific content generation. These modules migrate original logic from research-heavy Streamlit writers into standardized REST endpoints.
LinkedIn Content Generation
The LinkedIn service supports five primary content types with research-backed optimization.
- Generate Post: Creates industry-specific posts with hook and hashtag optimization.
- Generate Article: Produces long-form structured content with SEO.
- Generate Carousel: Provides multi-slide visual hierarchy and content.
Sources: backend/README_LINKEDIN_MIGRATION.md
Facebook Writer API
The Facebook API includes tools for both organic content and paid advertisements.
| Endpoint | Method | Input Description |
|---|---|---|
/post/generate | POST | Generates posts based on goal (engagement/reach) and tone. |
/ad-copy/generate | POST | Creates ad copy with targeting and budget-range suggestions. |
/reel/generate | POST | Generates video scripts with music and caption recommendations. |
/engagement/analyze | POST | Provides optimization tips based on content performance. |
Sources: backend/api/facebook_writer/README.md
System Health and Monitoring
The API provides granular health monitoring to ensure backend services, databases, and third-party AI providers are operational.
- Standard Health Check:
/health- General system status. - AI Service Health:
/health/ai- Status of connected LLM providers. - Database Health:
/health/database- Connection status for SQLite/PostgreSQL. - Module-Specific Health: e.g.,
/api/content-planning/enhanced-strategies/health.
Sources: SETUP_GUIDE.md, backend/api/content_planning/README.md
Summary
The ALwrity API Reference serves as the primary technical interface for the platform's content automation capabilities. By modularizing features into Content Planning, Social Media, and Onboarding services, the system maintains a clean separation of concerns. Developers can utilize the /docs (Swagger UI) or /redoc interactive documentation available at the backend root for real-time testing and detailed schema validation of request and response models.
Sources: backend/README.md, SETUP_GUIDE.md