# Agent Module API Documentation

This is the API documentation for the Agent Module, which includes training, marketing, messaging, goals, and reporting features.

## Table of Contents

1. [Authentication](#authentication)
2. [API Endpoints](#api-endpoints)
3. [Error Handling](#error-handling)
4. [Rate Limiting](#rate-limiting)
5. [Versioning](#versioning)

## Authentication

All API endpoints require authentication. The Agent Module uses token-based authentication.

Include the authentication token in the request header:

```
Authorization: Bearer {token}
```

To obtain a token, use the authentication endpoint:

```
POST /api/auth/login
```

With the following request body:

```json
{
  "email": "agent@example.com",
  "password": "your-password"
}
```

The response will include an access token:

```json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

## API Endpoints

The Agent Module API is divided into several sections:

1. [Training & Certification API](agent-training-api.md)
2. [Marketing Tools API](agent-marketing-api.md)
3. [Messaging & Communication API](agent-messaging-api.md)
4. [Goals & Reports API](agent-goals-reports-api.md)

## Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request.

Common status codes:

- `200 OK`: The request was successful
- `201 Created`: The resource was successfully created
- `400 Bad Request`: The request was invalid
- `401 Unauthorized`: Authentication failed
- `403 Forbidden`: The authenticated user does not have permission to access the resource
- `404 Not Found`: The requested resource was not found
- `422 Unprocessable Entity`: Validation error
- `500 Internal Server Error`: An error occurred on the server

Error responses include a JSON object with error details:

```json
{
  "error": "Error Type",
  "message": "Error message",
  "errors": {
    "field_name": [
      "Error message for field"
    ]
  }
}
```

## Rate Limiting

The API implements rate limiting to prevent abuse. The rate limits are as follows:

- 60 requests per minute per user
- 1000 requests per day per user

Rate limit information is included in the response headers:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1614556800
```

If you exceed the rate limit, you will receive a `429 Too Many Requests` response.

## Versioning

The API uses URL versioning. The current version is v1.

All endpoints are prefixed with `/api/v1/`.

When a new version is released, the old version will be maintained for a period of time to allow for a smooth transition.