marketing-assistant-ai/docs/API_DOCUMENTATION.md

# Marketing Assistant AI - API Documentation

## API Endpoints

### Generate Copy

Generates marketing copy based on the provided prompt and optional parameters.

**Endpoint**: `/generate-copy`  
**Method**: POST  
**Content-Type**: application/json

**Request Body**:
```json
{
  "prompt": "Write a social media post for our new product launch",
  "content_type": "social_media",
  "tone": "excited",
  "length": "medium",
  "include_cta": true
}
```

**Parameters**:
- `prompt` (string, required): The main instruction for generating content
- `content_type` (string, optional): Type of content to generate (social_media, email, blog, website, etc.)
- `tone` (string, optional): Desired tone (excited, professional, casual, etc.)
- `length` (string, optional): Content length (short, medium, long)
- `include_cta` (boolean, optional): Whether to include a call to action

**Response**:
```json
{
  "status": "success",
  "content": "Exciting news! Our revolutionary new product has just landed...",
  "suggestions": [
    "Alternative headline option 1",
    "Alternative headline option 2"
  ],
  "metadata": {
    "content_type": "social_media",
    "tone": "excited",
    "word_count": 85,
    "generated_at": "2025-04-17T10:30:45Z"
  }
}
```

### Get Brand Style Guidelines

Retrieves the current brand style guidelines.

**Endpoint**: `/brand-style`  
**Method**: GET

**Response**:
```json
{
  "brand_name": "Adriana James",
  "tone": ["professional", "friendly", "inspiring"],
  "voice_characteristics": ["clear", "direct", "empowering"],
  "taboo_words": ["cheap", "discount", "bargain"],
  "preferred_terms": {
    "customers": "clients",
    "products": "solutions"
  }
}
```

### Update Brand Style

Updates the brand style guidelines.

**Endpoint**: `/brand-style`  
**Method**: PUT  
**Content-Type**: application/json

**Request Body**:
```json
{
  "tone": ["professional", "friendly", "inspiring", "innovative"],
  "voice_characteristics": ["clear", "direct", "empowering"],
  "taboo_words": ["cheap", "discount", "bargain", "basic"],
  "preferred_terms": {
    "customers": "clients",
    "products": "solutions",
    "problems": "challenges"
  }
}
```

**Response**:
```json
{
  "status": "success",
  "message": "Brand style updated successfully"
}
```

### Add Training Data

Adds new marketing content for AI training.

**Endpoint**: `/training-data`  
**Method**: POST  
**Content-Type**: application/json

**Request Body**:
```json
{
  "content_type": "email_campaign",
  "content": "Dear valued client, We're thrilled to announce...",
  "metadata": {
    "campaign_name": "Spring Launch 2025",
    "performance_metrics": {
      "open_rate": 0.42,
      "click_rate": 0.15
    }
  }
}
```

**Response**:
```json
{
  "status": "success",
  "message": "Training data added successfully",
  "data_id": "12345"
}
```

### List Training Data

Retrieves a list of available training data.

**Endpoint**: `/training-data`  
**Method**: GET

**Query Parameters**:
- `content_type` (optional): Filter by content type
- `page` (optional): Page number for pagination
- `limit` (optional): Number of items per page

**Response**:
```json
{
  "items": [
    {
      "id": "12345",
      "content_type": "email_campaign",
      "preview": "Dear valued client, We're thrilled to announce...",
      "added_at": "2025-04-10T14:30:00Z"
    },
    {
      "id": "12346",
      "content_type": "social_media",
      "preview": "Exciting news! Our revolutionary new product...",
      "added_at": "2025-04-11T09:15:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "page": 1,
    "limit": 10,
    "pages": 5
  }
}
```

## Error Handling

All endpoints return standard HTTP status codes:

- `200 OK`: Request successful
- `400 Bad Request`: Invalid request parameters
- `401 Unauthorized`: Authentication failed
- `404 Not Found`: Resource not found
- `500 Internal Server Error`: Server-side error

Error response format:
```json
{
  "status": "error",
  "message": "Detailed error message",
  "error_code": "ERROR_CODE"
}
```