# API Reference

Complete API documentation for CiteFlow.

## Authentication

All API requests require authentication via Bearer token:

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.citeflow.ai/v1/sites
```

API keys are available on Agency plans.

## Base URL

```
https://api.citeflow.ai/v1
```

## Endpoints

### Sites

#### List Sites

```http
GET /sites
```

**Response**
```json
{
  "sites": [
    {
      "id": "site_abc123",
      "domain": "example.com",
      "createdAt": "2024-06-01T00:00:00Z"
    }
  ]
}
```

#### Create Site

```http
POST /sites
```

**Body**
```json
{
  "domain": "example.com"
}
```

**Response**
```json
{
  "id": "site_abc123",
  "domain": "example.com",
  "createdAt": "2024-06-01T00:00:00Z"
}
```

#### Delete Site

```http
DELETE /sites/{siteId}
```

### Bot Visits (Analytics)

#### Get Bot Visit Stats

```http
GET /bot-visits?siteId={siteId}&type=stats
```

**Query Parameters**
| Parameter | Type | Description |
|-----------|------|-------------|
| siteId | string | Required. Site identifier |
| type | string | stats, visits, or pages |
| botType | string | Filter by bot type |

**Response**
```json
{
  "success": true,
  "data": {
    "stats": {
      "totalVisits": 156,
      "todayVisits": 12,
      "uniqueBots": 5
    },
    "today": [...],
    "activeBots": [
      { "botType": "GPTBOT", "count": 89 },
      { "botType": "CLAUDEBOT", "count": 45 }
    ]
  }
}
```

#### Log Bot Visit

```http
POST /bot-visits
```

**Body**
```json
{
  "siteId": "site_abc123",
  "url": "/blog/post-1",
  "userAgent": "Mozilla/5.0 GPTBot/1.0",
  "referer": "https://example.com",
  "secFetchSite": "cross-site",
  "secFetchMode": "navigate",
  "ip": "192.168.1.1",
  "status": 200
}
```

**Response**
```json
{
  "success": true,
  "data": {
    "id": "bot_visit_123",
    "botType": "GPTBOT",
    "vendor": "openai",
    "category": "AI_CRAWLER"
  }
}
```

### Pages

#### Get Pages

```http
GET /pages?siteId={siteId}
```

**Query Parameters**
| Parameter | Type | Description |
|-----------|------|-------------|
| siteId | string | Required. Site identifier |
| status | string | Filter by status: hot, cooling, stale, never |
| search | string | Search by URL |

**Response**
```json
{
  "success": true,
  "data": {
    "pages": [
      {
        "id": "page_123",
        "url": "/blog/post-1",
        "crawlCount": 45,
        "referralCount": 12,
        "lastCrawlBy": "GPTBOT",
        "lastSeenAt": "2024-06-20T10:30:00Z",
        "status": "hot",
        "isIndexed": true
      }
    ]
  }
}
```

### Referrals

#### Get Referrals

```http
GET /referrals?siteId={siteId}
```

**Response**
```json
{
  "success": true,
  "data": {
    "totalVisits": 127,
    "topSource": "chatgpt",
    "sources": [
      {
        "source": "chatgpt",
        "visits": 68,
        "share": 54
      },
      {
        "source": "claude",
        "visits": 35,
        "share": 27
      }
    ],
    "dailyData": [
      { "date": "2024-06-20", "visits": 23 },
      { "date": "2024-06-21", "visits": 18 }
    ]
  }
}
```

### Tracker

#### Send Event

```http
POST /tracker
```

**Body**
```json
{
  "siteId": "site_abc123",
  "event": "pageview",
  "url": "/blog/post-1",
  "referrer": "https://chat.openai.com",
  "sessionId": "sess_xyz789"
}
```

**Event Types**
| Event | Description |
|-------|-------------|
| pageview | Page visit |
| session_start | New session |
| engagement | Time on page |
| route_change | SPA route change |

### Maintenance

#### Cleanup Crawler Logs

```http
POST /maintenance/cleanup?siteId={siteId}
```

**Response**
```json
{
  "success": true,
  "message": "Cleaned up 1250 CrawlerLog entries",
  "stats": {
    "totalBefore": 5000,
    "toDelete": 1250,
    "totalAfter": 3750,
    "deleted": 1250
  }
}
```

### Alerts

#### List Alerts

```http
GET /alerts?siteId={siteId}
```

**Response**
```json
{
  "success": true,
  "data": {
    "alerts": [
      {
        "id": "alert_123",
        "type": "new_bot",
        "message": "GPTBot visited your site for the first time",
        "createdAt": "2024-06-20T10:30:00Z"
      }
    ]
  }
}
```

## Rate Limits

| Plan | Requests/hour |
|------|---------------|
| Free | 100 |
| Starter | 500 |
| Pro | 1,000 |
| Agency | 10,000 |

## Error Codes

| Code | Description |
|------|-------------|
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid API key |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |

## Webhooks

Configure webhooks to receive real-time alerts.

### Events

| Event | Description |
|-------|-------------|
| bot.new | New AI bot detected |
| page.discovered | New page discovered |
| crawl.spike | Crawl activity spike |
| crawl.drop | Crawl activity drop |
| referral.spike | Referral traffic spike |

### Payload

```json
{
  "event": "bot.new",
  "siteId": "site_abc123",
  "data": {
    "botType": "GPTBOT",
    "url": "/blog/post-1",
    "timestamp": "2024-06-20T10:30:00Z"
  }
}
```

---

Next: [Deployment Guide](./deployment.md)