Content-Hunter_BE/docs/API_CONTRACTS.md

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

// 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

{
  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:

{
  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:

{
  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