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