# AdTogether REST API — LLM Integration Reference

**Version:** 0.1.26

> **Integration Guide:** For custom environments without a dedicated SDK, you can directly interface with the AdTogether Ad Serving API.

**Base URL:** `https://adtogether.relaxsoftwareapps.com`

### Fetch Ad

```bash
curl -X GET "https://adtogether.relaxsoftwareapps.com/api/ads/serve?country=global&adType=banner&apiKey=YOUR_APP_ID&bundleId=com.example.myapp&allowSelfAds=true&adUnitId=home_banner"
```

**Query parameters:**
| Param | Required | Description |
|-------|----------|-------------|
| `adUnitId` | no | Optional label for the ad placement (e.g. `home_banner`). Used for analytics grouping only. |
| `apiKey` | **yes** | Your registered app ID |
| `country` | no | Country code or `"global"` (default) |
| `bundleId` | no | Your app's bundle/package identifier |
| `allowSelfAds` | no | Show own ads as fallback (default: `true`) |
| `exclude` | no | Ad ID to exclude (for rotation) |
| `adType` | no | Filter by `"banner"` or `"interstitial"` |

Returns a JSON object:
```json
{
  "id": "ad_abc123",
  "title": "App Name",
  "description": "App description text",
  "imageUrl": "https://...",
  "clickUrl": "https://...",
  "token": "HMAC_SIGNATURE"
}
```

### Track Impression

```bash
curl -X POST "https://adtogether.relaxsoftwareapps.com/api/ads/impression" \
  -H "Content-Type: application/json" \
  -d '{
    "adId": "ad_abc123",
    "token": "HMAC_TOKEN_FROM_SERVE_RESPONSE",
    "apiKey": "YOUR_APP_ID",
    "bundleId": "com.example.myapp",
    "platform": "android",
    "environment": "production",
    "appName": "My App",
    "appVersion": "1.2.3"
  }'
```

### Track Click

```bash
curl -X POST "https://adtogether.relaxsoftwareapps.com/api/ads/click" \
  -H "Content-Type: application/json" \
  -d '{
    "adId": "ad_abc123",
    "token": "HMAC_TOKEN_FROM_SERVE_RESPONSE",
    "apiKey": "YOUR_APP_ID",
    "bundleId": "com.example.myapp",
    "platform": "web",
    "environment": "production"
  }'
```

### Tracking Payload Fields

| Field | Required | Description |
|-------|----------|-------------|
| `adId` | **yes** | The ad ID from the serve response |
| `token` | **yes** | HMAC signature from the serve response (requests without valid token are rejected) |
| `apiKey` | **yes** | Your registered app ID |
| `bundleId` | no | Your app's bundle/package identifier |
| `platform` | no | Platform identifier (e.g. `"android"`, `"ios"`, `"web"`, `"macos"`) |
| `environment` | no | `"development"` or `"production"` |
| `appName` | no | Human-readable app name |
| `appVersion` | no | App version string (e.g. `"1.2.3"`) |

> **Note:** While only `adId`, `token`, and `apiKey` are strictly required, providing `bundleId`, `platform`, and `environment` enables richer analytics in your dashboard.