# Groovinads Edge API

> Single REST surface for retail-media integrations with Groovinads. Three endpoints — events ingestion (`POST /v1/events`, fire-and-forget), ad render (`POST /v1/render`, synchronous, multi-format), and discovery (`GET /v1/formats`). Server-to-server only. Reuses the Groovinads platform's API Key → Session Token auth model.

## Endpoints

- `POST https://edge.groovinads.com/v1/events` — Send 1–500 events per call (mix event types and users freely). Returns `202 Accepted`. Accepts the canonical event types: `page_view`, `product_listing_view`, `product_view`, `cart`, `conversion`.
- `POST https://edge.groovinads.com/v1/render?format={data|component|html|webview}` — Returns a render descriptor (default), raw data, HTML, or the URL of an in-app slot for a mobile WebView (`webview`; the creative is fetched on the device, so new formats need no app release). Required body fields: `id_format`, `id_shop`, and one of `id_user`/`id_device`. The retail client is resolved from the Session Token (never sent). Optional `context` (url, referer, keywords, idcategory, sku_competing, recommend, locale, ip) drives contextual/behavioral selection.
- `GET  https://edge.groovinads.com/v1/formats` — List the ad formats of the shops owned by your retailer client (resolved from the Session Token). Optional filters: `id_shop`, `template`, `active`. Optional header: `x-id-clients`.

## Authentication

- Same model as DSP / Tracking / SDK APIs.
- Create an API Key in `https://admin.groovinads.com/`.
- Exchange it for a Session Token via `POST https://api.groovinads.com/v2/auth/session_token/request` with the API Key as the JSON body.
- Send every Edge call with `Authorization: Bearer <session_token>`. Pass `x-id-clients: <id>` for the client account context.

## Environments

- Production: `https://edge.groovinads.com/v1/`
- Sandbox:    `https://edge-dev.groovinads.com/v1/`

## Specifications

- OpenAPI 3.1:                   /openapi.yaml
- Events JSON Schema:            /schemas/events.v1.schema.json
- Render request JSON Schema:    /schemas/render-request.v1.schema.json
- Render descriptor JSON Schema: /schemas/render-descriptor.v1.schema.json
- Formats list JSON Schema:      /schemas/formats.v1.schema.json

## Docs (browse)

- Getting Started:           /
- Authentication Guide:      /authentication_guide
- Canonical Event Model:     /events/canonical-event-model
- Render Overview:           /render/overview
- Render Descriptor:         /descriptor/overview
- API Reference:             /api-resources/api-authentication
- SDKs:                      /sdk/overview
- Examples:                  /examples/node-server
- AI Agents:                 /agents/overview
- MCP Server:                /mcp

## Event types

- `page_view`            — generic non-PDP / non-listing page view
- `product_listing_view` — category or search results page (`idcategory` and/or `keywords`)
- `product_view`         — product detail page (`sku` required)
- `cart`                 — current cart contents (`items[{sku,qty}]`)
- `conversion`           — completed purchase (`idtransaction`, `goalvalue`, `idpixel`, `items[{sku,qty,subtotal}]`)

## Identity

- `uid`       — Groovinads first-party web user identifier, produced by the browser_match script provided during onboarding.
- `device_id` — mobile IDFA (iOS) or GAID (Android).
- Send at least one. Both is recommended when both are available.

## Render descriptor templates (v1.0)

- `carousel-3`, `carousel-5` — horizontal scroll of product cards
- `grid-2x2`                 — 4-card grid
- `banner-728x90`, `banner-300x250` — single image banners
- `native-list`              — vertical product list, host-styled
- `single-product`           — single product card, no chrome

## SDKs (official)

- JS / TS (Node, browser-via-proxy): `@groovinads/edge-sdk`
- React:                              `@groovinads/edge-react`
- iOS (SPM):                          `GroovinadsEdge`
- Android (Maven):                    `com.groovinads:edge`
- Flutter (private git dependency):   `groovinads_edge` — `GrvAdView` (WebView slot, recommended) and `GrvAd` (native rendering)

## MCP server

- `@groovinads/edge-mcp` — exposes `track_events`, `render_ad`, `list_formats`, `get_descriptor_schema`.

## Errors

- Error envelope: `{ "error": { "code", "message", "details" }, "request_id" }`.
- Common codes: `validation_error`, `unauthorized`, `forbidden`, `payload_too_large`, `not_found`, `no_match`, `internal_error`.

## Contact

- Email: dev@groovinads.com