generated from fahricansecer/boilerplate-be
338 lines
10 KiB
Markdown
338 lines
10 KiB
Markdown
# Content Hunter - API Contracts
|
|
|
|
## Overview
|
|
Complete API reference for all Content Hunter backend endpoints. All endpoints are RESTful and return JSON.
|
|
|
|
## Base URL
|
|
```
|
|
Production: https://api.contenthunter.app/v1
|
|
Development: http://localhost:3000/v1
|
|
```
|
|
|
|
## Authentication
|
|
All protected endpoints require Bearer token:
|
|
```
|
|
Authorization: Bearer <access_token>
|
|
```
|
|
|
|
---
|
|
|
|
## 1. Authentication (`/auth`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| POST | `/auth/register` | Register new user | ❌ |
|
|
| POST | `/auth/login` | Login with email/password | ❌ |
|
|
| POST | `/auth/google` | Google OAuth login | ❌ |
|
|
| POST | `/auth/refresh` | Refresh access token | ⚠️ |
|
|
| POST | `/auth/logout` | Logout user | ✅ |
|
|
| POST | `/auth/forgot-password` | Request password reset | ❌ |
|
|
| POST | `/auth/reset-password` | Reset password with token | ❌ |
|
|
|
|
### Request/Response Examples
|
|
|
|
```typescript
|
|
// POST /auth/register
|
|
Request: { email: string; password: string; name: string; }
|
|
Response: { user: User; accessToken: string; refreshToken: string; }
|
|
|
|
// POST /auth/login
|
|
Request: { email: string; password: string; }
|
|
Response: { user: User; accessToken: string; refreshToken: string; }
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Users (`/users`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/users/me` | Get current user | ✅ |
|
|
| PUT | `/users/me` | Update profile | ✅ |
|
|
| PUT | `/users/me/preferences` | Update preferences | ✅ |
|
|
| GET | `/users/me/credits` | Get credit balance | ✅ |
|
|
| DELETE | `/users/me` | Delete account | ✅ |
|
|
|
|
---
|
|
|
|
## 3. Workspaces (`/workspaces`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/workspaces` | List user workspaces | ✅ |
|
|
| POST | `/workspaces` | Create workspace | ✅ |
|
|
| GET | `/workspaces/:id` | Get workspace | ✅ |
|
|
| PUT | `/workspaces/:id` | Update workspace | ✅ |
|
|
| DELETE | `/workspaces/:id` | Delete workspace | ✅ |
|
|
| POST | `/workspaces/:id/members` | Add member | ✅ |
|
|
| DELETE | `/workspaces/:id/members/:userId` | Remove member | ✅ |
|
|
|
|
---
|
|
|
|
## 4. Content (`/content`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/content` | List content | ✅ |
|
|
| POST | `/content` | Create content | ✅ |
|
|
| GET | `/content/:id` | Get content | ✅ |
|
|
| PUT | `/content/:id` | Update content | ✅ |
|
|
| DELETE | `/content/:id` | Delete content | ✅ |
|
|
| POST | `/content/:id/variations` | Generate variations | ✅ |
|
|
| POST | `/content/:id/repurpose` | Repurpose content | ✅ |
|
|
|
|
---
|
|
|
|
## 5. Content Generation (`/content-generation`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| POST | `/content-generation/generate` | Generate content | ✅ |
|
|
| POST | `/content-generation/hooks` | Generate hooks | ✅ |
|
|
| POST | `/content-generation/threads` | Generate thread | ✅ |
|
|
| POST | `/content-generation/captions` | Generate captions | ✅ |
|
|
| POST | `/content-generation/scripts` | Generate video script | ✅ |
|
|
| GET | `/content-generation/styles` | Get writing styles | ✅ |
|
|
| POST | `/content-generation/styles` | Create custom style | ✅ |
|
|
|
|
### Content Generation Request
|
|
```typescript
|
|
{
|
|
type: 'post' | 'thread' | 'carousel' | 'video_script' | 'newsletter';
|
|
platform: 'x' | 'instagram' | 'linkedin' | 'tiktok' | 'youtube';
|
|
topic: string;
|
|
style?: string;
|
|
language?: ContentLanguage;
|
|
niche?: string;
|
|
variations?: number; // 1-3
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Trends (`/trends`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/trends` | Get aggregated trends | ✅ |
|
|
| GET | `/trends/google` | Google Trends | ✅ |
|
|
| GET | `/trends/twitter` | Twitter/X trends | ✅ |
|
|
| GET | `/trends/reddit` | Reddit trends | ✅ |
|
|
| GET | `/trends/news` | News trends | ✅ |
|
|
| POST | `/trends/youtube/transcript` | Extract YouTube transcript | ✅ |
|
|
| POST | `/trends/scrape` | Scrape web page | ✅ |
|
|
| POST | `/trends/scan` | Manual trend scan | ✅ |
|
|
|
|
---
|
|
|
|
## 7. Source Accounts (`/source-accounts`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/source-accounts` | List source accounts | ✅ |
|
|
| POST | `/source-accounts` | Add source account | ✅ |
|
|
| GET | `/source-accounts/:id` | Get source account | ✅ |
|
|
| DELETE | `/source-accounts/:id` | Remove source | ✅ |
|
|
| GET | `/source-accounts/:id/posts` | Get source posts | ✅ |
|
|
| POST | `/source-accounts/:id/analyze` | Analyze viral post | ✅ |
|
|
|
|
---
|
|
|
|
## 8. Neuro Marketing (`/neuro-marketing`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/neuro-marketing/triggers` | Get psychology triggers | ✅ |
|
|
| GET | `/neuro-marketing/hooks` | Get emotional hooks | ✅ |
|
|
| GET | `/neuro-marketing/patterns` | Get engagement patterns | ✅ |
|
|
| POST | `/neuro-marketing/analyze` | Analyze content psychology | ✅ |
|
|
| POST | `/neuro-marketing/optimize` | Optimize for engagement | ✅ |
|
|
|
|
---
|
|
|
|
## 9. SEO (`/seo`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/seo/keywords` | Search keywords | ✅ |
|
|
| POST | `/seo/analyze` | Analyze content SEO | ✅ |
|
|
| POST | `/seo/optimize` | Optimize for SEO | ✅ |
|
|
| GET | `/seo/suggestions` | Get keyword suggestions | ✅ |
|
|
|
|
---
|
|
|
|
## 10. Visual Generation (`/visual-generation`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| POST | `/visual-generation/image` | Generate image | ✅ |
|
|
| POST | `/visual-generation/video` | Generate video (Veo) | ✅ |
|
|
| GET | `/visual-generation/templates` | Get templates | ✅ |
|
|
| POST | `/visual-generation/templates` | Create template | ✅ |
|
|
| PUT | `/visual-generation/templates/:id` | Update template | ✅ |
|
|
|
|
---
|
|
|
|
## 11. Video & Thumbnails (`/video-thumbnail`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| POST | `/video-thumbnail/script` | Generate video script | ✅ |
|
|
| POST | `/video-thumbnail/thumbnail` | Generate thumbnail | ✅ |
|
|
| POST | `/video-thumbnail/title` | Optimize video title | ✅ |
|
|
| GET | `/video-thumbnail/patterns` | Get thumbnail patterns | ✅ |
|
|
|
|
---
|
|
|
|
## 12. Social Integration (`/social`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/social/accounts` | List connected accounts | ✅ |
|
|
| POST | `/social/connect/:platform` | Connect platform | ✅ |
|
|
| DELETE | `/social/disconnect/:platform` | Disconnect platform | ✅ |
|
|
| POST | `/social/publish` | Publish content | ✅ |
|
|
| GET | `/social/status/:postId` | Get publish status | ✅ |
|
|
|
|
---
|
|
|
|
## 13. Scheduling (`/scheduling`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/scheduling/calendar` | Get calendar view | ✅ |
|
|
| POST | `/scheduling/calendar/event` | Create event | ✅ |
|
|
| PUT | `/scheduling/calendar/event/:id` | Update event | ✅ |
|
|
| DELETE | `/scheduling/calendar/event/:id` | Delete event | ✅ |
|
|
| GET | `/scheduling/workflows` | Get workflow templates | ✅ |
|
|
| POST | `/scheduling/workflows` | Create workflow | ✅ |
|
|
| GET | `/scheduling/timing/:platform` | Get optimal times | ✅ |
|
|
| GET | `/scheduling/queue` | Get post queue | ✅ |
|
|
| POST | `/scheduling/queue` | Add to queue | ✅ |
|
|
| GET | `/scheduling/automation` | Get automation rules | ✅ |
|
|
| POST | `/scheduling/automation` | Create automation | ✅ |
|
|
|
|
---
|
|
|
|
## 14. Analytics (`/analytics`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| POST | `/analytics/engagement` | Record engagement | ✅ |
|
|
| GET | `/analytics/dashboard/overview` | Dashboard overview | ✅ |
|
|
| GET | `/analytics/dashboard/heatmap` | Engagement heatmap | ✅ |
|
|
| GET | `/analytics/gold-posts` | Get gold posts | ✅ |
|
|
| POST | `/analytics/ab-tests` | Create A/B test | ✅ |
|
|
| GET | `/analytics/ab-tests/:id` | Get test results | ✅ |
|
|
| GET | `/analytics/growth-formulas` | Get growth formulas | ✅ |
|
|
| POST | `/analytics/growth-formulas` | Create formula | ✅ |
|
|
| GET | `/analytics/webhooks` | List webhooks | ✅ |
|
|
| POST | `/analytics/webhooks` | Create webhook | ✅ |
|
|
|
|
---
|
|
|
|
## 15. Subscriptions (`/subscriptions`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/subscriptions/plans` | Get available plans | ❌ |
|
|
| GET | `/subscriptions/current` | Get current subscription | ✅ |
|
|
| POST | `/subscriptions/checkout` | Create checkout session | ✅ |
|
|
| POST | `/subscriptions/cancel` | Cancel subscription | ✅ |
|
|
| POST | `/subscriptions/webhook` | Stripe webhook | ❌ |
|
|
|
|
---
|
|
|
|
## 16. Credits (`/credits`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/credits/balance` | Get balance | ✅ |
|
|
| GET | `/credits/history` | Get usage history | ✅ |
|
|
| POST | `/credits/purchase` | Purchase credits | ✅ |
|
|
| GET | `/credits/packages` | Get credit packages | ❌ |
|
|
|
|
---
|
|
|
|
## 17. Languages (`/languages`)
|
|
|
|
| Method | Endpoint | Description | Auth |
|
|
|--------|----------|-------------|------|
|
|
| GET | `/languages` | List supported languages | ❌ |
|
|
| GET | `/languages/:code` | Get language details | ❌ |
|
|
| GET | `/languages/:code/guide` | Get cultural guide | ❌ |
|
|
|
|
---
|
|
|
|
## Error Response Format
|
|
|
|
All errors follow this structure:
|
|
```typescript
|
|
{
|
|
statusCode: number;
|
|
message: string;
|
|
error: string;
|
|
timestamp: string;
|
|
path: string;
|
|
}
|
|
```
|
|
|
|
### Common Status Codes
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| 200 | Success |
|
|
| 201 | Created |
|
|
| 400 | Bad Request |
|
|
| 401 | Unauthorized |
|
|
| 403 | Forbidden |
|
|
| 404 | Not Found |
|
|
| 429 | Rate Limited |
|
|
| 500 | Server Error |
|
|
|
|
---
|
|
|
|
## Rate Limits
|
|
|
|
| Plan | Requests/min | Requests/day |
|
|
|------|-------------|--------------|
|
|
| Free | 10 | 100 |
|
|
| Starter | 30 | 1,000 |
|
|
| Pro | 60 | 5,000 |
|
|
| Ultimate | 100 | 20,000 |
|
|
| Enterprise | Unlimited | Unlimited |
|
|
|
|
---
|
|
|
|
## Pagination
|
|
|
|
List endpoints support pagination:
|
|
```
|
|
GET /content?page=1&limit=20&sort=createdAt&order=desc
|
|
```
|
|
|
|
Response includes:
|
|
```typescript
|
|
{
|
|
data: T[];
|
|
meta: {
|
|
total: number;
|
|
page: number;
|
|
limit: number;
|
|
totalPages: number;
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## WebSocket Events
|
|
|
|
Connect to: `wss://api.contenthunter.app/ws`
|
|
|
|
| Event | Direction | Description |
|
|
|-------|-----------|-------------|
|
|
| `content.generated` | Server→Client | Content generation complete |
|
|
| `publish.status` | Server→Client | Publish status update |
|
|
| `trend.alert` | Server→Client | New trend detected |
|
|
| `gold.detected` | Server→Client | Gold post detected |
|