> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Referrals API: Push AI-Sourced Traffic Data

> Push pre-aggregated daily referral events from Adobe Analytics and other tools into Scrunch to power the AI Traffic dashboard and Site Map metrics.

## Overview

The AI Referrals API ingests pre-aggregated daily traffic that originated from AI assistants (ChatGPT, Claude, Perplexity, and so on) into Scrunch. Use it when your source of truth for web analytics is **Adobe Analytics** or another tool you'd like to push from on a schedule, rather than connecting Google Analytics directly.

Once a connection is registered and events start landing, the AI Traffic dashboard and the Site Map's `ai_referrals` metric prefer push data over any live-queried Google Analytics integration for the same website.

***

## When to use the AI Referrals API

Use this API when you need to:

* Send AI-sourced traffic from **Adobe Analytics** into Scrunch on a daily schedule.
* Backfill historical AI referral data from any pre-aggregated source.
* Power the AI Traffic dashboard for brands that don't use Google Analytics.

If your team uses **Google Analytics 4**, connect it through the in-app integration instead — you don't need this API. A brand cannot have both a Google Analytics integration and an active AI Referrals push connection on the same website at the same time.

***

## How it works

1. **Register a connection** for the `(brand, website, provider)` you'll push from. Connections are scoped to one website each; register multiple connections if you push for several domains.
2. **Push events** in batches against that connection. Each event is one row of pre-aggregated daily metrics — pageviews, sessions, transactions, and revenue — keyed by date, referrer, and page.
3. **Read results** on the AI Traffic dashboard and via the Sitemap API's `ai_referrals` totals.

Pushes are **idempotent**. The upsert key is `(date, raw_referrer_value, raw_page_value)` — resending the same tuple replaces the prior values, so retries and corrections are safe.

***

## Authentication

All endpoints use Bearer-token authentication. Connection writes require the `configure` scope; listing requires the `query` scope.

```bash theme={null}
export SCRUNCH_API_TOKEN="your-key"
```

Generate a key under **Organization → Settings → API Keys** in the Scrunch dashboard.

***

## Endpoints

| Method   | Path                                                          | Purpose                                                  |
| -------- | ------------------------------------------------------------- | -------------------------------------------------------- |
| `POST`   | `/{brand_id}/ai-referrals/connections`                        | Register a push connection for one website and provider. |
| `GET`    | `/{brand_id}/ai-referrals/connections`                        | List the brand's push connections.                       |
| `DELETE` | `/{brand_id}/ai-referrals/connections/{connection_id}`        | Soft-disable a connection.                               |
| `POST`   | `/{brand_id}/ai-referrals/connections/{connection_id}/events` | Push a batch of pre-aggregated daily events.             |

The list endpoint returns push connections only. Google Analytics integrations live in a separate system and don't appear here, even when they're the reason a register call returned `409`.

***

## Supported providers

The MVP allow-list is:

* `adobe_analytics`

More providers will be added behind the same `provider` field — your code doesn't need to change when the allow-list grows.

***

## Event schema

Each event is one pre-aggregated daily row.

| Field                | Type                  | Required | Description                                                                                                        |
| -------------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `date`               | string (`YYYY-MM-DD`) | Yes      | UTC calendar day the metrics cover.                                                                                |
| `raw_referrer_value` | string                | Yes      | Raw referrer from the source tool (e.g. `chatgpt.com`). Normalized server-side against the AI platform allow-list. |
| `raw_page_value`     | string                | Yes      | Raw page identifier — URL path for GA-shape tools, page name for Adobe unless a URL eVar is configured.            |
| `pageviews`          | integer               | No       | Pageviews for the row. Must be ≥ 0.                                                                                |
| `sessions`           | integer               | No       | Sessions for the row. Must be ≥ 0.                                                                                 |
| `transactions`       | integer               | No       | Completed transactions, when available.                                                                            |
| `purchase_revenue`   | number                | No       | Revenue attributed to the row.                                                                                     |
| `batch_id`           | string                | No       | Optional client-supplied identifier for traceability.                                                              |

***

## Example: register a connection

```bash theme={null}
curl -X POST "https://api.scrunchai.com/v1/1234/ai-referrals/connections" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "website": "example.com",
    "provider": "adobe_analytics"
  }'
```

**Response:**

```json theme={null}
{
  "id": "01JX2Y6E8H1AKQ8V0W7G4D9SXT",
  "brand_id": 1234,
  "website": "example.com",
  "provider": "adobe_analytics",
  "status": "active",
  "created_at": "2026-05-24T12:00:00Z",
  "last_pushed_at": null,
  "last_push_error": null
}
```

Save the returned `id` — you'll use it as `connection_id` on every push.

***

## Example: push a batch (JSON array)

```bash theme={null}
curl -X POST \
  "https://api.scrunchai.com/v1/1234/ai-referrals/connections/01JX2Y6E8H1AKQ8V0W7G4D9SXT/events" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "date": "2026-05-20",
      "raw_referrer_value": "chatgpt.com",
      "raw_page_value": "/blog/launch-notes",
      "pageviews": 412,
      "sessions": 298,
      "transactions": 7,
      "purchase_revenue": 1842.50
    },
    {
      "date": "2026-05-20",
      "raw_referrer_value": "perplexity.ai",
      "raw_page_value": "/pricing",
      "pageviews": 88,
      "sessions": 71
    }
  ]'
```

**Response:**

```json theme={null}
{
  "accepted": 2,
  "rejected": 0,
  "errors": []
}
```

Events whose `raw_referrer_value` doesn't match Scrunch's AI platform allow-list are counted in `rejected` rather than failing the whole batch.

***

## Example: push a batch (NDJSON)

For larger batches, send newline-delimited JSON to reduce parser overhead:

```bash theme={null}
curl -X POST \
  "https://api.scrunchai.com/v1/1234/ai-referrals/connections/01JX2Y6E8H1AKQ8V0W7G4D9SXT/events" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary $'{"date":"2026-05-20","raw_referrer_value":"chatgpt.com","raw_page_value":"/blog/a","pageviews":12}\n{"date":"2026-05-20","raw_referrer_value":"claude.ai","raw_page_value":"/blog/b","pageviews":3}'
```

***

## Limits

* **10,000 events per batch.** Larger batches return `413 Payload Too Large` — split and retry.
* **5 MB request body.** Same `413` behavior.
* One **active** connection per `(brand_id, website)`. Disable the existing connection or use a different website before re-registering.

***

## Status codes

| Status | Meaning                                                                             |
| ------ | ----------------------------------------------------------------------------------- |
| `200`  | Batch accepted. The response body reports `accepted` and `rejected` counts.         |
| `201`  | Connection registered.                                                              |
| `400`  | Malformed payload, invalid provider, or empty body.                                 |
| `404`  | Brand or connection not found.                                                      |
| `409`  | A connection or conflicting integration already exists for this `(brand, website)`. |
| `410`  | Connection is disabled — re-register before pushing again.                          |
| `413`  | Batch exceeds the 10,000-event or 5 MB cap.                                         |
| `422`  | One or more events failed schema validation. The body includes per-row errors.      |

***

## Best practices

* **Push once per day** after your source tool has finalized the prior day's data. The upsert key makes re-pushes safe, but daily granularity is enough for the dashboard.
* **Send raw referrer values** straight from your source tool — don't pre-normalize. Scrunch maps them to AI platforms server-side and that mapping evolves over time.
* **Include `batch_id`** when you can. It makes it easier to correlate a push with your ETL run if you need to investigate later.
* **Back off on `429`/`5xx`** with exponential retry. Pushes are idempotent on the upsert key.
* **Don't mix providers** on one connection. Register one connection per `(website, provider)`.