my-pixel-api

---
name: my-pixel-api
version: 1.0.0
description: >
  Tracking pixel + identity resolution for MyAPI funnels and email. Capture visits and events, resolve known users to anonymous sessions, stream interaction events for analytics. Pairs with mycrmapi for auto-ingest of pixel_visit events on known contacts.
triggers: [pixel, analytics, tracking, visit, event, identity, session, attribution, geo, open pixel]
checksum: sha256-pending
---

# MyPixelAPI

A lightweight pixel data layer for funnels published via **myfunnelapi** and emails sent via **myemailapi**. Reads visits, events, identity resolutions, and interaction streams. The analytics half of the loop between outbound (email/funnel) and the CRM.

## Capabilities
<!-- llm:start -->

### What lands in the pixel layer

- **Visits** — page-visit records scoped to a website host (`from_url`, `to_url`, `pixel_id`, timestamp). `--website <domain>` is required.
- **Events** — typed engagement events: `sent`, `open`, `click`, `page_visit`. Requires at least one filter: `--campaign-id` or `--domain`.
- **Interactions** — a unified timeline of visits + events. Requires at least one filter: `--website`, `--campaign-id`, or `--domain`.
- **Identity** — given a `pixel_id` plus the `--website <domain>` it was seen on, resolve its identity graph (`{uuid, is_resolved, nodes, …}`).
- **Audience** — a geographic distribution sample of the org's pixel audience (`myapi pixel audience`, no subcommand).

### Identity stitching

The cookie-bridge pixel (`/t/p`) is a cross-domain pixel used to stitch an anonymous session on one MyAPI funnel to the same browser on another. The open-pixel (`/t/o`) is the 1x1 transparent gif embedded in outbound email and resolves the email recipient's session when they open the mail.

### CRM auto-ingest (when wired)

When pixel `identify` events fire with a known email, the CRM service auto-creates / upserts a contact and writes a `pixel_visit` event on its timeline. Today this hook lives in the hypersearch service and needs to move to the integrated stack — until then, pixel data and CRM data live in separate stores.

### Retention

Pixel data lives ~90 days hot; aggregated geo/audience samples persist longer. Don't depend on individual-event-level data being available indefinitely — promote anything you need long-term into the CRM as a custom event.

### When to use

- **Campaign attribution** — did the people you emailed actually visit?
- **Funnel optimization** — which page is dropping off?
- **Audience definition** — build a Goldfox/CRM filter from observed visit behavior
- **Re-engagement** — pull the list of contacts whose `pixel_visit` is more than N days old
<!-- llm:end -->

## Commands
<!-- generated:start -->
| Command | What it does |
|---|---|
| `myapi pixel visits --website <domain> [--from <iso>] [--to <iso>] [--limit N] [--offset N]` | Page-visit timeline scoped to a website host |
| `myapi pixel events (--campaign-id <id> \| --domain <domain>) [--from <iso>] [--to <iso>] [--limit N] [--offset N]` | Engagement events (sent / open / click / page_visit). Requires at least one filter: `--campaign-id` or `--domain` |
| `myapi pixel interactions [--website <domain>] [--campaign-id <id>] [--domain <domain>] [--from <iso>] [--to <iso>] [--limit N] [--offset N]` | Unified timeline of visits + events |
| `myapi pixel identity <pixel_id> --website <domain>` | Resolve a pixel ID's identity graph (returns `{uuid, is_resolved, nodes, …}`) |
| `myapi pixel audience` | Geographic distribution sample of your pixel audience |
<!-- generated:end -->

## Examples
<!-- llm:start -->
```bash
# Page visits on a funnel host (--website is required for visits)
myapi pixel visits --website acme.com --limit 50

# Engagement events for a campaign (event_type: sent | open | click | page_visit)
myapi pixel events --campaign-id q2-launch --from 2026-06-01 --to 2026-06-30

# Events by domain instead of campaign
myapi pixel events --domain acme.com --limit 100

# Unified timeline (visits + events) — needs at least one filter
myapi pixel interactions --website acme.com

# Resolve a pixel ID's identity graph (--website is required)
myapi pixel identity px_abc123 --website acme.com
# → { "uuid": "...", "is_resolved": true, "nodes": [ ... ] }

# Geographic distribution sample of the org's pixel audience
myapi pixel audience
```
<!-- llm:end -->

## Notes

- **Privacy.** Pixel data captures sessions, not personal info beyond what your funnel/email forms collect. Identity resolution only works when a known identifier was passed in via your code or the cookie-bridge.
- **No write API for synthetic events** — the pixel records what the embedded JS/email-pixel observes. To inject custom timeline entries, use `myapi crm contacts/{id}/events` instead (when reserved-kind allows; today event writes are platform-only).
- **`my-crm-api` is the durable record.** Pixel data ages out at ~90 days; CRM events are permanent. If a behavioral signal matters for long-term targeting, promote it into the CRM.

Run `myapi pixel --help` for inline reference.

## Status

**Backend reads are GA; agent-facing skill content is draft.** This skill publishes (status flips from `planned` to `ga` in `services.ts`) once pixel → CRM auto-ingest is wired so the cross-primitive examples above resolve end-to-end.