Skip to documentation
PoolstatisDocs
Integrations

HTTP and custom integrations

Use the HTTP ingest API when a framework-specific wrapper is unavailable. This path works for server-rendered sites, CMS templates, backend jobs, mobile gateways, and custom runtimes. MCP is still the trusted agent interface for registry and queries; it is not the event transport.

Send an event

curl -sS -X POST "$POOLSTATIS_URL/i/v1/events" \
  -H "Authorization: Bearer $POOLSTATIS_INGEST_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "batch_id": "deploy-check-001",
    "events": [{
      "event": "signup.completed",
      "distinct_id": "user_opaque_42",
      "session_id": "session_opaque_7",
      "properties": { "plan": "free" }
    }]
  }'

The bearer token must be the write-only pk_ key for the intended project and environment. Never use sk_ or pt_ in a public page, CMS template, mobile bundle, or Tag Manager.

The batch accepts at most 500 events. batch_id is the client idempotency key: reuse it when retrying the same batch. A mixed-validity batch can return HTTP 207 with per-element errors. Unregistered events are stored with registered=false; they are not silently dropped.

Update an entity

curl -sS -X POST "$POOLSTATIS_URL/i/v1/entities" \
  -H "Authorization: Bearer $POOLSTATIS_INGEST_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "entities": [{
      "entity_type": "account",
      "entity_id": "account_opaque_7",
      "properties": { "plan": "pro", "seats": 4 }
    }]
  }'

Entity updates merge supplied properties. A null property removes that key. Use events for facts over time and entities only for current state.

Browser and SPA integration

Do not reproduce Browser analytics by manually sending full URLs or user agents. Use the published @poolstatis/sdk@0.4.0 Browser entrypoint from Browser analytics so route mapping, session rotation, UTM allowlisting, and payload bounds remain consistent. For Bitrix, see Bitrix integration.

Verify through MCP

list_projects()
sample_events(project, { event: "signup.completed", limit: 20, env: "prod" })
get_onboarding_status(project, { env: "prod" })
query_trend(project, {
  metric: "signup_completed",
  date_from: "-7d",
  interval: "day",
  env: "prod"
})

The visible acceptance gate is one durably stored event, the expected project/environment, an active purpose-first metric, and a typed query result. A successful curl alone is not proof that the semantic measurement is ready.