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

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

Commands

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

Examples

# 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

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.