# URL Redirect Tracker API Documentation

This API allows you to programmatically track and analyze URL redirect chains, providing detailed information about each redirect, including HTTP status codes, headers, and response data.

## Rate Limiting

The API is limited to 100 requests per hour per IP address.

## API Endpoints

### POST /api/v1/track

Track a URL and get the full redirect chain using a POST request.

#### Request Parameters (JSON Body)

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string | Yes | The URL to track (e.g., "example.com" or "https://example.com") |
| method | string | No | HTTP method to use (GET, HEAD, POST). Default: "GET" |
| userAgent | string | No | Custom User-Agent header to send with the request |

#### Example Request

```bash
curl -X POST https://urltrackertool.com/api/v1/track \
  -H "Content-Type: application/json" \
  -d '{
    "url": "github.com",
    "method": "GET",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome"
  }'
```

### GET /api/v1/track

Track a URL and get the full redirect chain using a GET request with query parameters.

#### Request Parameters (Query String)

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string | Yes | The URL to track (e.g., "example.com" or "https://example.com") |
| method | string | No | HTTP method to use (GET, HEAD, POST). Default: "GET" |
| userAgent | string | No | Custom User-Agent header to send with the request |

#### Example Request

```bash
curl "https://urltrackertool.com/api/v1/track?url=github.com&method=GET&userAgent=Mozilla%2F5.0%20Chrome"
```

## Response Format

Both endpoints return the same JSON structure:

```json
{
  "success": true,
  "status": 200,
  "data": {
    "url": "http://github.com",
    "method": "GET",
    "redirectCount": 1,
    "finalUrl": "https://github.com/",
    "finalStatusCode": 200,
    "redirects": [
      {
        "url": "http://github.com",
        "timestamp": 1684320000000,
        "isSSL": false,
        "duration": 220,
        "statusCode": 301,
        "statusText": "Moved Permanently",
        "metadata": {
          "status": 301,
          "statusText": "Moved Permanently",
          "headers": {
            "location": "https://github.com/",
            "content-length": "0",
            "server": "GitHub.com"
          },
          "contentType": "text/html",
          "contentLength": "0",
          "server": "GitHub.com",
          "date": "Wed, 17 May 2023 12:00:00 GMT",
          "protocol": "http:",
          "method": "GET"
        }
      },
      {
        "url": "https://github.com/",
        "timestamp": 1684320000220,
        "isSSL": true,
        "duration": 350,
        "statusCode": 200,
        "statusText": "OK",
        "metadata": {
          "status": 200,
          "statusText": "OK",
          "headers": {
            "content-type": "text/html; charset=utf-8",
            "server": "GitHub.com"
          },
          "contentType": "text/html; charset=utf-8",
          "server": "GitHub.com",
          "date": "Wed, 17 May 2023 12:00:00 GMT",
          "protocol": "https:",
          "method": "GET"
        },
        "final": true
      }
    ]
  }
}
```

## Error Codes

| Status Code | Description |
|-------------|-------------|
| 400 | Bad Request - Required parameters are missing or invalid |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Server Error - An error occurred while processing the request |

## JavaScript Example

```javascript
const trackUrl = async (url) => {
  const response = await fetch('https://urltrackertool.com/api/v1/track', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url,
      method: 'GET'
    })
  });
  
  return await response.json();
};

// Usage
trackUrl('github.com')
  .then(data => console.log(data))
  .catch(err => console.error(err));
```

## Python Example

```python
import requests

def track_url(url):
    response = requests.post(
        'https://urltrackertool.com/api/v1/track',
        json={
            'url': url,
            'method': 'GET'
        }
    )
    return response.json()

# Usage
result = track_url('github.com')
print(result)
```