Base code
This commit is contained in:
Kunthawat Greethong
433
docs-site/docs/api/overview.md
Normal file
433
docs-site/docs/api/overview.md
Normal file
@@ -0,0 +1,433 @@
|
||||
# API Reference Overview
|
||||
|
||||
ALwrity provides a comprehensive RESTful API that allows you to integrate AI-powered content creation capabilities into your applications. This API enables you to generate blog posts, optimize SEO, create social media content, and manage your content strategy programmatically.
|
||||
|
||||
## Base URL
|
||||
|
||||
```
|
||||
Development: http://localhost:8000
|
||||
Production: https://your-domain.com
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
ALwrity uses API key authentication for secure access to endpoints.
|
||||
|
||||
### API Key Setup
|
||||
|
||||
1. **Get your API key** from the ALwrity dashboard
|
||||
2. **Include in requests** using the `Authorization` header:
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
https://your-domain.com/api/blog-writer
|
||||
```
|
||||
|
||||
## API Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Client Applications"
|
||||
Web[Web Application]
|
||||
Mobile[Mobile App]
|
||||
CLI[CLI Tools]
|
||||
ThirdParty[Third-party Apps]
|
||||
end
|
||||
|
||||
subgraph "API Gateway"
|
||||
Auth[Authentication]
|
||||
RateLimit[Rate Limiting]
|
||||
Validation[Request Validation]
|
||||
Routing[Request Routing]
|
||||
end
|
||||
|
||||
subgraph "Core Services"
|
||||
Blog[Blog Writer API]
|
||||
SEO[SEO Dashboard API]
|
||||
LinkedIn[LinkedIn Writer API]
|
||||
Strategy[Content Strategy API]
|
||||
end
|
||||
|
||||
subgraph "AI Services"
|
||||
Gemini[Gemini AI]
|
||||
Research[Research Services]
|
||||
Analysis[SEO Analysis]
|
||||
Generation[Content Generation]
|
||||
end
|
||||
|
||||
subgraph "Data Layer"
|
||||
DB[(Database)]
|
||||
Cache[(Redis Cache)]
|
||||
Files[File Storage]
|
||||
end
|
||||
|
||||
Web --> Auth
|
||||
Mobile --> Auth
|
||||
CLI --> Auth
|
||||
ThirdParty --> Auth
|
||||
|
||||
Auth --> RateLimit
|
||||
RateLimit --> Validation
|
||||
Validation --> Routing
|
||||
|
||||
Routing --> Blog
|
||||
Routing --> SEO
|
||||
Routing --> LinkedIn
|
||||
Routing --> Strategy
|
||||
|
||||
Blog --> Gemini
|
||||
Blog --> Research
|
||||
SEO --> Analysis
|
||||
LinkedIn --> Generation
|
||||
Strategy --> Research
|
||||
|
||||
Blog --> DB
|
||||
SEO --> DB
|
||||
LinkedIn --> DB
|
||||
Strategy --> DB
|
||||
|
||||
Blog --> Cache
|
||||
SEO --> Cache
|
||||
|
||||
Generation --> Files
|
||||
|
||||
style Auth fill:#ffebee
|
||||
style Blog fill:#e3f2fd
|
||||
style SEO fill:#e8f5e8
|
||||
style LinkedIn fill:#fff3e0
|
||||
style Strategy fill:#f3e5f5
|
||||
```
|
||||
|
||||
## Core Endpoints
|
||||
|
||||
### Blog Writer API
|
||||
|
||||
#### Generate Blog Content
|
||||
```http
|
||||
POST /api/blog-writer
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
|
||||
{
|
||||
"topic": "AI in Digital Marketing",
|
||||
"target_audience": "Marketing professionals",
|
||||
"content_type": "how-to-guide",
|
||||
"word_count": 1500,
|
||||
"tone": "professional"
|
||||
}
|
||||
```
|
||||
|
||||
#### Research Integration
|
||||
```http
|
||||
POST /api/blog-writer/research
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
|
||||
{
|
||||
"topic": "Content Strategy",
|
||||
"research_depth": "comprehensive",
|
||||
"sources": ["web", "academic", "industry"]
|
||||
}
|
||||
```
|
||||
|
||||
#### SEO Analysis
|
||||
```http
|
||||
POST /api/blog-writer/seo/analyze
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
|
||||
{
|
||||
"content": "Your blog post content here...",
|
||||
"target_keywords": ["content strategy", "digital marketing"],
|
||||
"competitor_urls": ["https://example.com"]
|
||||
}
|
||||
```
|
||||
|
||||
### SEO Dashboard API
|
||||
|
||||
#### Performance Analysis
|
||||
```http
|
||||
GET /api/seo-dashboard/performance
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
|
||||
{
|
||||
"domain": "your-website.com",
|
||||
"date_range": "30d",
|
||||
"metrics": ["traffic", "rankings", "conversions"]
|
||||
}
|
||||
```
|
||||
|
||||
#### Keyword Research
|
||||
```http
|
||||
POST /api/seo-dashboard/keywords/research
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
|
||||
{
|
||||
"seed_keywords": ["digital marketing", "content creation"],
|
||||
"language": "en",
|
||||
"location": "US",
|
||||
"competition_level": "medium"
|
||||
}
|
||||
```
|
||||
|
||||
#### Content Optimization
|
||||
```http
|
||||
POST /api/seo-dashboard/optimize
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
|
||||
{
|
||||
"content": "Your content here...",
|
||||
"target_keyword": "content strategy",
|
||||
"optimization_goals": ["readability", "keyword_density", "structure"]
|
||||
}
|
||||
```
|
||||
|
||||
### LinkedIn Writer API
|
||||
|
||||
#### Generate LinkedIn Content
|
||||
```http
|
||||
POST /api/linkedin-writer
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
|
||||
{
|
||||
"content_type": "post",
|
||||
"topic": "Professional networking tips",
|
||||
"tone": "professional",
|
||||
"include_hashtags": true,
|
||||
"target_audience": "LinkedIn professionals"
|
||||
}
|
||||
```
|
||||
|
||||
#### Fact Checking
|
||||
```http
|
||||
POST /api/linkedin-writer/fact-check
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
|
||||
{
|
||||
"content": "Your LinkedIn post content...",
|
||||
"verification_level": "comprehensive"
|
||||
}
|
||||
```
|
||||
|
||||
### Content Strategy API
|
||||
|
||||
#### Generate Strategy
|
||||
```http
|
||||
POST /api/content-strategy/generate
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
|
||||
{
|
||||
"business_type": "SaaS",
|
||||
"target_audience": "Small business owners",
|
||||
"goals": ["lead_generation", "brand_awareness"],
|
||||
"content_types": ["blog", "social", "email"]
|
||||
}
|
||||
```
|
||||
|
||||
#### Persona Development
|
||||
```http
|
||||
POST /api/content-strategy/personas
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
|
||||
{
|
||||
"business_niche": "Digital marketing",
|
||||
"target_demographics": {
|
||||
"age_range": "25-45",
|
||||
"profession": "Marketing professionals",
|
||||
"pain_points": ["time_management", "roi_tracking"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response Formats
|
||||
|
||||
### Success Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"content": "Generated content here...",
|
||||
"metadata": {
|
||||
"word_count": 1500,
|
||||
"readability_score": 85,
|
||||
"seo_score": 92
|
||||
}
|
||||
},
|
||||
"timestamp": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Error Response
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "INVALID_REQUEST",
|
||||
"message": "Missing required parameter: topic",
|
||||
"details": {
|
||||
"parameter": "topic",
|
||||
"expected_type": "string"
|
||||
}
|
||||
},
|
||||
"timestamp": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
| Plan | Requests per Minute | Requests per Day |
|
||||
|------|-------------------|------------------|
|
||||
| Free | 10 | 100 |
|
||||
| Basic | 60 | 1,000 |
|
||||
| Pro | 300 | 10,000 |
|
||||
| Enterprise | 1,000 | 100,000 |
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| `INVALID_API_KEY` | API key is missing or invalid |
|
||||
| `RATE_LIMIT_EXCEEDED` | Too many requests |
|
||||
| `INVALID_REQUEST` | Request parameters are invalid |
|
||||
| `CONTENT_TOO_LONG` | Content exceeds maximum length |
|
||||
| `QUOTA_EXCEEDED` | Daily quota exceeded |
|
||||
| `SERVICE_UNAVAILABLE` | Service temporarily unavailable |
|
||||
|
||||
## SDKs and Libraries
|
||||
|
||||
### Python
|
||||
```bash
|
||||
pip install alwrity-python
|
||||
```
|
||||
|
||||
```python
|
||||
from alwrity import AlwrityClient
|
||||
|
||||
client = AlwrityClient(api_key="YOUR_API_KEY")
|
||||
|
||||
# Generate blog content
|
||||
response = client.blog_writer.generate(
|
||||
topic="AI in Marketing",
|
||||
word_count=1000,
|
||||
tone="professional"
|
||||
)
|
||||
|
||||
print(response.content)
|
||||
```
|
||||
|
||||
### JavaScript/Node.js
|
||||
```bash
|
||||
npm install alwrity-js
|
||||
```
|
||||
|
||||
```javascript
|
||||
const AlwrityClient = require('alwrity-js');
|
||||
|
||||
const client = new AlwrityClient('YOUR_API_KEY');
|
||||
|
||||
// Generate LinkedIn content
|
||||
client.linkedinWriter.generate({
|
||||
content_type: 'post',
|
||||
topic: 'Professional development',
|
||||
tone: 'inspirational'
|
||||
}).then(response => {
|
||||
console.log(response.content);
|
||||
});
|
||||
```
|
||||
|
||||
### cURL Examples
|
||||
|
||||
#### Generate Blog Post
|
||||
```bash
|
||||
curl -X POST "https://your-domain.com/api/blog-writer" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"topic": "Content Marketing Trends 2024",
|
||||
"word_count": 1200,
|
||||
"tone": "professional"
|
||||
}'
|
||||
```
|
||||
|
||||
#### SEO Analysis
|
||||
```bash
|
||||
curl -X POST "https://your-domain.com/api/blog-writer/seo/analyze" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"content": "Your content here...",
|
||||
"target_keywords": ["content marketing", "trends"]
|
||||
}'
|
||||
```
|
||||
|
||||
## Webhooks
|
||||
|
||||
ALwrity supports webhooks for real-time notifications about content generation and processing status.
|
||||
|
||||
### Webhook Events
|
||||
|
||||
- `content.generated` - Content generation completed
|
||||
- `seo.analysis.completed` - SEO analysis finished
|
||||
- `strategy.updated` - Content strategy updated
|
||||
- `quota.warning` - Approaching quota limit
|
||||
|
||||
### Webhook Configuration
|
||||
|
||||
```http
|
||||
POST /api/webhooks
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer YOUR_API_KEY
|
||||
|
||||
{
|
||||
"url": "https://your-app.com/webhooks/alwrity",
|
||||
"events": ["content.generated", "seo.analysis.completed"],
|
||||
"secret": "your_webhook_secret"
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### API Usage
|
||||
|
||||
1. **Use HTTPS**: Always use HTTPS for API requests
|
||||
2. **Handle Errors**: Implement proper error handling
|
||||
3. **Rate Limiting**: Respect rate limits and implement backoff
|
||||
4. **Caching**: Cache responses when appropriate
|
||||
5. **Monitoring**: Monitor API usage and performance
|
||||
|
||||
### Content Generation
|
||||
|
||||
1. **Be Specific**: Provide detailed topic descriptions
|
||||
2. **Set Expectations**: Specify word count and tone
|
||||
3. **Review Output**: Always review generated content
|
||||
4. **Iterate**: Use feedback to improve results
|
||||
|
||||
### Security
|
||||
|
||||
1. **Protect API Keys**: Never expose API keys in client-side code
|
||||
2. **Use Environment Variables**: Store keys securely
|
||||
3. **Rotate Keys**: Regularly rotate API keys
|
||||
4. **Monitor Usage**: Track API usage for anomalies
|
||||
|
||||
## Support
|
||||
|
||||
### Documentation
|
||||
- **[Authentication Guide](authentication.md)** - Detailed authentication setup
|
||||
- **[Rate Limiting](rate-limiting.md)** - Understanding rate limits
|
||||
- **[Error Handling](error-codes.md)** - Complete error reference
|
||||
|
||||
### Getting Help
|
||||
- **GitHub Issues**: [Report bugs and request features](https://github.com/AJaySi/ALwrity/issues)
|
||||
- **API Status**: Check [API status page](https://status.alwrity.com)
|
||||
- **Community**: Join our [developer community](https://discord.gg/alwrity)
|
||||
|
||||
---
|
||||
|
||||
*Ready to integrate ALwrity into your application? [Get your API key](https://dashboard.alwrity.com/api-keys) and start building!*
|
||||
Reference in New Issue
Block a user