# MyPixelAPI

> Turn anonymous traffic into identified interactions

Base URL: https://api.mypixelapi.com

Authentication: `Authorization: Bearer <your_api_key>`

MyPixelAPI exposes the interactions collected by the tracking pixel (pixel_visits and email_events tracking logs).

All routes are under /pixel/ and require API key authentication.

Key endpoints:
- GET /pixel/interactions?website=domain.com&from=RFC3339&to=RFC3339&limit=50&offset=0 — merged visits+events timeline. Requires at least website or campaign_id.
- GET /pixel/visits?website=domain.com&from=&to=&limit=&offset= — raw page visits.
- GET /pixel/events?campaign_id=X&domain=yourdomain.com&from=&to=&limit=&offset= — email events (sent/open/click) filtered by campaign or clicked URL domain. open events always have empty meta.
- GET /pixel/identity/{pixel_id} — full identity dossier for a pixel (emails, IPs, fingerprints, visits).

All list responses include: data array, total count, limit, offset.
Identity response includes: pixel_id, emails[], ips[], l0_fps[], l1_fps[], locations[], networks[], visits[], raw_nodes[].
- GET /pixel/audience/get_geo_sample?lat=X&lon=Y&radius=2000 — fast geographic extraction of identities based on H3 cells.


## Agent Onboarding

To use this or any other MyAPIHQ service as an autonomous agent, follow these steps:

1. **Register an Agent Account**:
   Create an agent account. Returns `account_id`, `pin`, and a `token` (JWT) in one call — no email or human required.
   ```bash
   curl -X POST https://api.myapihq.com/hq/account/agent/create \
     -H "Content-Type: application/json" \
     -d '{"label": "my-agent"}'
   ```

2. **Create a Permanent API Key**:
   Use the `token` from step 1 to create a workspace-scoped API key (`hq_live_...`).
   ```bash
   curl -X POST https://api.myapihq.com/hq/account/create/key \
     -H "Authorization: Bearer <token_from_step_1>" \
     -H "Content-Type: application/json" \
     -d '{"name": "my-agent-key"}'
   ```

3. **Authenticate**:
   All subsequent requests must include: `Authorization: Bearer <your_api_key>`.
   The JWT token from step 1 is valid for account and billing endpoints only.
   All service calls (orgs, funnels, email, domains) require the API key from step 2.

## Endpoints

### GET /pixel/interactions
**Get Unified Interaction Timeline**
Returns a merged, time-sorted list of web visits and email events. Requires at least one of `website`, `domain`, or `campaign_id`.

**Parameters:**
- `website` (query): Filter visits by destination domain (matches to_url). (type: string)
- `domain` (query): Filter email events by clicked URL domain (matches meta.url). (type: string)
- `campaign_id` (query): Filter email events by campaign ID (utm_campaign value). (type: string)
- `from` (query): Start of date range (RFC3339). (type: string)
- `to` (query): End of date range (RFC3339). (type: string)
- `limit` (query):  (type: integer)
- `offset` (query):  (type: integer)

**Response (JSON):**
```json
{
  "interactions": Array<{
    "type": string (visit|event),
    "pixel_id": string,
    "from_url": string,
    "to_url": string,
    "event_type": string (sent|open|click|page_visit),
    "url": string,
    "campaign_id": string,
    "ts": string
  }>,
  "total_visits": integer,
  "total_events": integer,
  "limit": integer,
  "offset": integer
}
```


### GET /pixel/visits
**Get Web Visits**
Returns paginated page visits for a website domain.

**Parameters:**
- `website` (query): Website domain to filter by. (type: string)
- `from` (query):  (type: string)
- `to` (query):  (type: string)
- `limit` (query):  (type: integer)
- `offset` (query):  (type: integer)

**Response (JSON):**
```json
{
  "visits": Array<{
    "pixel_id": string,
    "from_url": string,
    "to_url": string,
    "ts": string
  }>,
  "total": integer,
  "limit": integer,
  "offset": integer
}
```


### GET /pixel/events
**Get Email Events**
Returns paginated email events (sent/open/click) optionally filtered by campaign_id or domain. Note: open events always have empty meta.

**Parameters:**
- `campaign_id` (query): Campaign ID (utm_campaign value) to filter by. (type: string)
- `domain` (query): Filter by clicked URL domain (matches meta.url LIKE '%domain%'). Only matches click events. (type: string)
- `from` (query):  (type: string)
- `to` (query):  (type: string)
- `limit` (query):  (type: integer)
- `offset` (query):  (type: integer)

**Response (JSON):**
```json
{
  "events": Array<{
    "pixel_id": string,
    "event_type": string (sent|open|click|page_visit),
    "url": string,
    "campaign_id": string,
    "ts": string
  }>,
  "total": integer,
  "limit": integer,
  "offset": integer
}
```


### GET /pixel/identity/{id}
**Get Pixel Identity**
Resolves a pixel_id to its full identity dossier via graph resolution: emails, IPs, fingerprints, locations, networks, and recent visits.

**Parameters:**
- `id` (path): The pixel UUID. (type: string, Required)

**Response (JSON):**
```json
{
  "pixel_id": string,
  "emails": Array<string>,
  "ips": Array<string>,
  "l0_fps": Array<string>,
  "l1_fps": Array<string>,
  "locations": Array<string>,
  "networks": Array<string>,
  "visits": Array<{
    "from": string,
    "to": string,
    "time": string
  }>,
  "raw_nodes": Array<{
    "value": string,
    "type": string,
    "probability": number
  }>
}
```


### GET /pixel/audience/get_geo_sample
**Get Geo Sample (Audience)**
Fast geographic extraction of identities utilizing ClickHouse H3 array intersections.

**Parameters:**
- `lat` (query): Latitude for coordinate search (type: number)
- `lon` (query): Longitude for coordinate search (type: number)
- `q` (query): Text search (resolved internally to coordinates) (type: string)
- `radius` (query): Radius in meters (type: integer)

**Response (JSON):**
```json
{
  "latency_ms": number,
  "lat": number,
  "lon": number,
  "radius_m": number,
  "people": Array<object>,
  "companies": Array<object>
}
```


## Pricing

Pay per use. No subscription.

---
## Ecosystem Integration
This service is part of the MyAPIHQ ecosystem. You authenticate using an API Key generated from your MyAPIHQ account.
To view the full list of available services (like domain registration, funnel building, transactional email, object storage, etc.), fetch [https://myapihq.com/llms.txt](https://myapihq.com/llms.txt).