# Telegram Marketing Agent System API Documentation

## Overview

The Telegram Marketing Agent System provides a comprehensive REST API for managing marketing campaigns, user segmentation, message scheduling, and analytics. This documentation covers all available endpoints, authentication requirements, and usage examples.

## Base URL

```
http://localhost:3000/api/v1
```

## Authentication

All API endpoints (except login and public endpoints) require JWT authentication. Include the JWT token in the Authorization header:

```
Authorization: Bearer <your-jwt-token>
```

## Getting Started

1. **Login to get access token**
   ```bash
   curl -X POST http://localhost:3000/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{"username": "admin", "password": "password123"}'
   ```

2. **Use the token for subsequent requests**
   ```bash
   curl -X GET http://localhost:3000/api/v1/campaigns \
     -H "Authorization: Bearer <your-token>"
   ```

## API Documentation Sections

### Core Services

1. [Authentication API](./auth-api.md) - User authentication and session management
2. [Campaigns API](./campaigns-api.md) - Campaign creation and management
3. [Analytics API](./analytics-api.md) - Real-time analytics and reporting
4. [Users API](./users-api.md) - User management and segmentation

### Marketing Features

5. [Templates API](./templates-api.md) - Message template management
6. [Scheduled Campaigns API](./scheduled-campaigns-api.md) - Campaign scheduling
7. [A/B Testing API](./ab-testing-api.md) - A/B test management
8. [Workflows API](./workflows-api.md) - Marketing automation workflows

### Integration Services

9. [Webhooks API](./webhooks-api.md) - Webhook integration management
10. [Translations API](./translations-api.md) - Multi-language support
11. [AI API](./ai-api.md) - Claude AI integration for smart suggestions

### System Management

12. [Accounts API](./accounts-api.md) - Telegram account management
13. [Compliance API](./compliance-api.md) - Compliance checking
14. [Settings API](./settings-api.md) - System configuration

## Interactive API Explorer

Access the Swagger UI at: `http://localhost:3000/api-docs`

## Rate Limiting

- Default rate limit: 100 requests per minute per IP
- Authenticated users: 1000 requests per minute
- AI endpoints: 20 requests per minute

## Error Handling

All API errors follow a consistent format:

```json
{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}
```

### Common Error Codes

- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `429` - Too Many Requests
- `500` - Internal Server Error

## Pagination

List endpoints support pagination:

```
GET /api/v1/campaigns?page=1&limit=20&sort=-createdAt
```

- `page` - Page number (default: 1)
- `limit` - Items per page (default: 20, max: 100)
- `sort` - Sort field, prefix with `-` for descending

## Filtering

Most list endpoints support filtering:

```
GET /api/v1/campaigns?status=active&type=message
```

## Webhooks

Configure webhooks to receive real-time notifications:

1. Register webhook endpoint
2. Verify webhook signature
3. Handle webhook events

See [Webhooks API](./webhooks-api.md) for details.

## SDKs and Libraries

- [Node.js SDK](https://github.com/yourusername/tg-marketing-sdk-node)
- [Python SDK](https://github.com/yourusername/tg-marketing-sdk-python)
- [PHP SDK](https://github.com/yourusername/tg-marketing-sdk-php)

## Support

- API Status: `http://localhost:3000/health`
- Contact: api-support@yourcompany.com
- GitHub: https://github.com/yourusername/telegram-marketing-agent