# API Endpoint: [Method] [Endpoint Path]

## Overview
Brief description of what this endpoint does and when to use it.

## Authentication
- **Required**: Yes/No
- **Type**: Bearer Token / API Key / None
- **Permissions**: List required permissions

## Request

### HTTP Method & URL
```http
[METHOD] /api/v1/[endpoint]
```

### Headers
```http
Content-Type: application/json
Authorization: Bearer <your-token>
```

### Path Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | string | Yes | Unique identifier |

### Query Parameters  
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| page | number | No | 1 | Page number for pagination |
| limit | number | No | 20 | Number of items per page |

### Request Body
```json
{
  "field1": "string",
  "field2": "number", 
  "field3": {
    "nested": "object"
  }
}
```

#### Request Schema
| Field | Type | Required | Validation | Description |
|-------|------|----------|------------|-------------|
| field1 | string | Yes | 1-100 chars | Field description |
| field2 | number | No | > 0 | Field description |

## Response

### Success Response (200/201)
```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "field1": "string",
    "field2": "number",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  },
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "pages": 5
    }
  }
}
```

### Error Responses

#### 400 Bad Request
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}
```

#### 401 Unauthorized
```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
```

#### 403 Forbidden
```json
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}
```

#### 404 Not Found
```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}
```

#### 500 Internal Server Error
```json
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Something went wrong"
  }
}
```

## Rate Limiting
- **Limit**: 1000 requests per hour per user
- **Headers**: 
  - `X-RateLimit-Limit`: Total requests allowed
  - `X-RateLimit-Remaining`: Requests remaining
  - `X-RateLimit-Reset`: Reset time (Unix timestamp)

## Examples

### cURL Example
```bash
curl -X [METHOD] "https://api.yourdomain.com/api/v1/[endpoint]" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -d '{
    "field1": "example value",
    "field2": 123
  }'
```

### JavaScript Example
```javascript
const response = await fetch('/api/v1/[endpoint]', {
  method: '[METHOD]',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token-here'
  },
  body: JSON.stringify({
    field1: 'example value',
    field2: 123
  })
});

const data = await response.json();
console.log(data);
```

### Python Example
```python
import requests

url = 'https://api.yourdomain.com/api/v1/[endpoint]'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token-here'
}
data = {
    'field1': 'example value',
    'field2': 123
}

response = requests.[method](url, headers=headers, json=data)
result = response.json()
print(result)
```

## Testing

### Unit Test Example
```typescript
describe('[METHOD] /api/v1/[endpoint]', () => {
  it('should return success with valid data', async () => {
    const response = await request(app)
      .[method]('/api/v1/[endpoint]')
      .send({
        field1: 'test value',
        field2: 123
      })
      .expect(200);

    expect(response.body.success).toBe(true);
    expect(response.body.data).toMatchObject({
      field1: 'test value',
      field2: 123
    });
  });

  it('should return 400 for invalid data', async () => {
    const response = await request(app)
      .[method]('/api/v1/[endpoint]')
      .send({
        field1: '', // Invalid empty string
        field2: -1  // Invalid negative number
      })
      .expect(400);

    expect(response.body.success).toBe(false);
    expect(response.body.error.code).toBe('VALIDATION_ERROR');
  });
});
```

## Notes
- Additional implementation notes
- Performance considerations
- Security considerations
- Related endpoints

## Changelog
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2024-01-01 | Initial implementation |

---
**Last Updated**: [Date]  
**Reviewed By**: [Name]  
**Next Review**: [Date]