canonical: https://jentic.com/apis/jirafe.com/jirafe-main

# Jirafe Events

This is the primary Jirafe Events API for the Jirafe e-commerce analytics platform. Six endpoints accept structured events for cart actions, product views, category browsing, customer signups, and order completion, plus a /batch endpoint for high-volume ingest. Events are scoped per Jirafe site through the {siteId} path parameter, and authentication uses OAuth 2.0 (authorization-code or implicit). Ingested events feed Jirafe's funnels, retention, and merchandising analyses.

## For AI agents

Send e-commerce events (cart, product, category, customer, order) into Jirafe for analytics, individually or via the batch endpoint.

## Scope

Does not run reports, manage dashboards, or expose stored event history - use for sending e-commerce events into Jirafe only.

## Capabilities

- Send cart-add, cart-remove, and cart-checkout events to /{siteId}/cart
- Send product-view events with SKU and price metadata to /{siteId}/product
- Send category-browse events to /{siteId}/category for funnel analysis
- Send customer events (signup, login, profile-update) to /{siteId}/customer
- Send order-completion events with line items and totals to /{siteId}/order
- Submit batches of mixed events in one request to /{siteId}/batch for high-volume ingest

## Use cases

### Storefront Event Tracking

An e-commerce storefront sends cart, product, and order events to Jirafe Events from server-side hooks so the analytics platform can build funnels (visit -> product view -> cart -> checkout -> order). Server-side ingest is more reliable than client beacons because it survives ad blockers and tab closures.

Example prompt: POST a cart event to /{siteId}/cart with action=add, productId=SKU123, quantity=2, and price=29.99 from the storefront's add-to-cart hook.

### Backfill via Batch Ingest

When migrating to Jirafe or replaying historical orders, sending events one-at-a-time is rate-limit-prone and slow. The /{siteId}/batch endpoint accepts an array of mixed event types in a single request, suitable for nightly replays of the day's orders or one-off historical backfills of months of data.

Example prompt: POST a JSON array of order events to /{siteId}/batch covering yesterday's orders, then verify the response confirms each event was accepted.

### Customer Lifecycle Analytics

Combining customer events (signup, login) with downstream cart and order events lets Jirafe compute time-to-first-purchase, repeat-rate, and churn signals. Sending each lifecycle moment to the matching event endpoint is the prerequisite for any of these reports inside Jirafe's dashboard.

Example prompt: On user registration POST a customer signup event to /{siteId}/customer; on first checkout POST an order event to /{siteId}/order with the same customerId.

### AI Agent Integration via Jentic

An e-commerce agent uses Jentic to discover Jirafe ingest operations by intent. The agent searches for 'send a cart event to analytics' and Jentic returns the /{siteId}/cart operation, so the agent posts the event without reading Jirafe docs. The OAuth token stays in your Jentic One instance.

Example prompt: Search Jentic for 'send an order event to Jirafe', load the POST /{siteId}/order schema, and execute it with the order's line items and totals.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/{siteId}/cart` | Send a cart event |
| POST | `/{siteId}/product` | Send a product event |
| POST | `/{siteId}/order` | Send an order event |
| POST | `/{siteId}/customer` | Send a customer event |
| POST | `/{siteId}/batch` | Submit a batch of events |

## Key resources

- **Cart** — Send cart-action events (add, remove, checkout) per site.
- **Product** — Send product-view events with SKU and price.
- **Category** — Send category-browse events for funnel analysis.
- **Customer** — Send customer-lifecycle events (signup, login).
- **Order** — Send order-completion events with line items and totals.
- **Batch** — Submit mixed event arrays in a single request for backfill or high-volume ingest.

## Why Jentic

- **Setup:** Wiring the Jirafe Events API by hand means running its OAuth flow and posting e-commerce events under the right site path yourself. Through Jentic you install once, import Jirafe Events from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Jirafe puts the site id in the URL path (/{siteId}/cart, /{siteId}/order), so a rule can pin your agent to one site: it can send events only for that site. You choose the operations it may call, such as cart or order events, so it stays within sending events into Jirafe.
- **Credential handling:** Your Jirafe OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a cart event to analytics', and Jentic returns the matching Jirafe Events operation with its body schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Segment API** — Segment is a vendor-neutral event pipeline that fans events out to many destinations, while Jirafe Events ingests directly into the Jirafe analytics product
- **Mixpanel API** — Mixpanel offers product-analytics event ingest with deeper funnel and retention reporting than Jirafe
- **Amplitude API** — Run Amplitude alongside Jirafe to cover both web/app product analytics and e-commerce funnels

## FAQ

### What authentication does Jirafe Events use?

OAuth 2.0 - both authorization-code and implicit flows are declared in the spec. Send the resulting access token as a Bearer token on each event POST. Through Jentic the OAuth flow is brokered and tokens are kept in the vault rather than the agent context.

### Can I send a batch of events in one request to Jirafe?

Yes. POST a JSON array of events to /{siteId}/batch. This is the right choice for backfills and any case where you'd otherwise rate-limit yourself by sending many single-event requests in a tight loop.

### What are the rate limits for Jirafe Events?

Jirafe does not publish a fixed limit in the spec; the documented guidance is to use /{siteId}/batch for high-volume ingest. If single-event POSTs return 429, switch to batch and retry with exponential backoff.

### How do I send a product-view event through Jentic?

Run pip install jentic, search for 'send a product view event to analytics', then load and execute POST /{siteId}/product with the productId, name, and price. Jentic injects the OAuth token automatically.

### Do I need a separate site ID for each storefront?

Yes - every event endpoint is scoped by the {siteId} path parameter, which corresponds to a Jirafe site (typically one per storefront or brand). Provision sites in the Jirafe dashboard before sending events.

### Is Jirafe Events free?

Jirafe pricing is plan-based and not exposed by the API itself. Existing Jirafe customers should consult their account; new evaluators should contact Jirafe to confirm the current commercial terms.

### Can I limit what my agent is allowed to do with the Jirafe Events API?

Yes. Because Jentic One is self-hosted, you write the rules that decide which Jirafe Events operations and credentials your agent may use. Since the Jirafe site id lives in the URL path (/{siteId}/cart, /{siteId}/order), you can pin the agent to a single site so it only sends events for that storefront. You also choose which operations it may call, for example allowing cart and order event POSTs while withholding the batch endpoint, so it stays within sending events into Jirafe.