Docs/Reference/Partner API

Reference · Partner API

Partner API

Read-only programmatic access to events, logs, and sessions. Built for CI pipelines, AI agents, and custom integrations that need data without the Dashboard.

01Overview

Every request authenticates with a bearer token minted under Settings → API Tokens.

Base URLhttps://api.sumidata.io

AuthAuthorization: Bearer sumi_…

Content-Typeapplication/json

ScopeRead-only - no event ingest here

Tokens are scoped to a single project. Project filtering is applied automatically from the token - never pass projectId in query params.

The Partner API is read-only. In the browser, record orders with Sumidata.purchase(order) - see Conversions. To send events from a backend, use POST /sdk/ingest (the SDK ingest endpoint, authenticated by projectId in the JSON body - no Bearer token).

02Query DSL

All list endpoints share the same filter syntax.

The pattern is q[field__action]=value. Multiple filters combine with AND. Fields an endpoint does not support and unknown actions are silently ignored, not rejected.

Filter actions

Action	SQL	Example
`__eq`	`= value`	`q[level__eq]=error`
`__not`	`!= value`	`q[source__not]=sdk`
`__in`	`IN (...)`	`q[level__in]=error,warn`
`__cont`	`LIKE '%v%'`	`q[message__cont]=Checkout`
`__like`	`ILIKE '%v%'`	`q[name__like]=page`
`__gte`	`>= value`	`q[timestamp__gte]=2026-01-01`
`__lte`	`<= value`	`q[timestamp__lte]=2026-04-01`
`__is`	`IS NULL` · `IS NOT NULL`	`q[sessionId__is]=null` · `not_null`
`__order`	`ORDER BY`	`q[timestamp__order]=desc`
`order`	`ORDER BY`	`q[order]=timestamp:asc`

Pagination

q[page] (default 1) and q[perPage] (default 50, max 200).

03Endpoints

Five endpoints - health, events, logs, sessions, schema validation. All read-only GETs.

GET

https://api.sumidata.io/api/partner/healthGET /api/partner/health

Integration health - when the last event was received, rough throughput numbers. No query params. Used by CI pipelines and monitoring.

Example request

curl

curl "https://api.sumidata.io/api/partner/health" \
  -H "Authorization: Bearer sumi_…"

Success · 200 OK

response.json

{
  "status": "healthy",  // "healthy" | "warning" | "error"
  "projectId": "5d0e8a3c-…",
  "lastEventAt": "2026-04-20 09:12:44.000",
  "lastLogAt": "2026-04-20 09:10:02.000",
  "eventsLastHour": 142,
  "logsLastHour": 58,
  "sessionsLastHour": 23
}

status is healthy when the last event arrived within 5 min, warning within 60 min, error otherwise (or if no events exist yet).

Errors

401	`Valid API token required. Use Authorization: Bearer sumi_xxx`	Missing `Authorization` header, or it does not start with `Bearer sumi_`
401	`Invalid or revoked API token`	Token not found, or revoked

GET

https://api.sumidata.io/api/partner/eventsGET /api/partner/events

List events, filtered by the query DSL. Returns a paginated array ordered by timestamp descending by default.

Query parameters

Name	Type	Required	Description
`q[name__eq]`	string	-	Exact event name match
`q[name__like]`	string	-	Substring match on event name
`q[externalUserId__eq]`	string	-	Restrict to a single user
`q[sessionId__eq]`	UUID	-	Restrict to one session
`q[source__eq]`	string	-	Filter by origin (e.g. `sdk`, `backend`, `import`)
`q[timestamp__gte]`	ISO-8601	-	Inclusive lower bound on event time
`q[timestamp__lte]`	ISO-8601	-	Inclusive upper bound
`q[createdAt__gte]`	ISO-8601	-	Lower bound on server ingest time
`q[url__like]`	string	-	Substring match on page URL
`q[platform__eq]`	string	-	Operating system (e.g. `Linux`)
`q[browser__eq]`	string	-	Browser (e.g. `Chrome`)
`q[orderId__not]`	string	-	Send it empty (`q[orderId__not]=`) to list only conversions
`q[currency__eq]`	string	-	Conversion currency
`q[utmSource__eq]`	string	-	UTM source snapshot on the event
`q[utmMedium__eq]`	string	-	UTM medium snapshot on the event
`q[utmCampaign__eq]`	string	-	UTM campaign snapshot on the event
`q[page]`	int	-	1-based. Default 1
`q[perPage]`	int	-	1–200. Default 50

Example request

curl

curl -g "https://api.sumidata.io/api/partner/events?q[name__eq]=purchase&q[timestamp__gte]=2026-04-01" \
  -H "Authorization: Bearer sumi_…"

Success · 200 OK

response.json

{
  "events": [
    {
      "id": "8b1f4e2a-…",
      "name": "purchase",
      "payload": "{…}",  // JSON string
      "sessionId": "…",
      "externalUserId": "user_7e2a9c",
      "timestamp": "2026-04-20 09:12:44.000",
      "url": "https://app.example.com/checkout",
      "platform": "Linux",
      "browser": "Chrome",
      "source": "sdk"
    }
  ],
  "totalCount": 1432,
  "page": 1,
  "perPage": 50
}

Conversion fields (orderId, totalAmount, currency, utmSource…) are columns on the same row, not inside payload, and this endpoint does not return them or an order's line items. Use q[orderId__not]= to list only conversions, or filter by name. payload contains only the free-form fields you sent - metadata (_category/_feature/_surface) is stripped into the per-project dictionary at ingest.

Errors

401	`Valid API token required. Use Authorization: Bearer sumi_xxx`	Missing `Authorization` header, or it does not start with `Bearer sumi_`
401	`Invalid or revoked API token`	Token not found, or revoked
500	`Internal Server Error`	A `q[…]` value does not parse as the field's type (e.g. a non-UUID `sessionId`)

GET

https://api.sumidata.io/api/partner/logsGET /api/partner/logs

Query project logs. Use q[level__eq]=error to get only errors.

Query parameters

Name	Type	Required	Description
`q[level__eq]`	enum	-	`debug` · `info` · `warn` · `error`
`q[level__in]`	csv	-	Multiple levels, comma-separated (e.g. `error,warn`)
`q[message__like]`	string	-	Substring match on log message
`q[source__eq]`	string	-	`sdk` · `backend`
`q[sessionId__eq]`	UUID	-	Restrict to one session
`q[timestamp__gte]`	ISO-8601	-	Inclusive lower bound
`q[timestamp__lte]`	ISO-8601	-	Inclusive upper bound
`q[createdAt__gte]`	ISO-8601	-	Lower bound on server ingest time
`q[url__like]`	string	-	Substring match on page URL
`q[platform__eq]`	string	-	Operating system
`q[browser__eq]`	string	-	Browser

Example request

curl

curl -g "https://api.sumidata.io/api/partner/logs?q[level__in]=error,warn&q[perPage]=20" \
  -H "Authorization: Bearer sumi_…"

Success · 200 OK

response.json

{
  "logs": [{
    "id": "c47a9d10-…",
    "level": "error",
    "message": "Checkout failed: invalid token",
    "payload": "{…}",  // JSON string
    "source": "sdk",
    "sessionId": "…",
    "timestamp": "2026-04-20 09:12:44.000",
    "url": "https://app.example.com/checkout"
  }],
  "totalCount": 39,
  "page": 1,
  "perPage": 20
}

GET

https://api.sumidata.io/api/partner/sessionsGET /api/partner/sessions

List project sessions with UTM attribution, device info, and landing page.

Query parameters

Name	Type	Required	Description
`q[externalUserId__eq]`	string	-	Your user ID
`q[deviceId__eq]`	UUID	-	Device identifier
`q[utmSource__eq]`	string	-	UTM source
`q[utmMedium__eq]`	string	-	UTM medium
`q[utmCampaign__eq]`	string	-	UTM campaign
`q[utmTerm__eq]`	string	-	UTM term
`q[utmContent__eq]`	string	-	UTM content
`q[referrer__like]`	string	-	Substring match on referrer
`q[landingPage__like]`	string	-	Substring match on landing page URL
`q[platform__eq]`	string	-	Operating system
`q[browser__eq]`	string	-	Browser
`q[ip__eq]`	string	-	Visitor IP address
`q[source__eq]`	string	-	`sdk` (recorded by the SDK) or `import` (imported sessions)
`q[startedAt__gte]`	ISO-8601	-	Session start lower bound
`q[createdAt__gte]`	ISO-8601	-	Lower bound on when Sumidata stored the session (import time for imported sessions)
`q[visitorKind__eq]`	enum	-	`human` · `bot` · `ai_agent_declared` · `ai_agent_suspected`. Filter only, not in the response
`q[agentName__eq]`	string	-	Name of the matched bot or AI agent. Filter only, not in the response

Example request

curl

curl -g "https://api.sumidata.io/api/partner/sessions?q[externalUserId__eq]=user_7e2a9c" \
  -H "Authorization: Bearer sumi_…"

Success · 200 OK

response.json

{
  "sessions": [{
    "id": "1e6b7f93-…",
    "deviceId": "…",
    "externalUserId": "user_7e2a9c",
    "platform": "Linux",
    "browser": "Chrome",
    "screenSize": "1920x1080",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "spring-2026",
    "utmTerm": "",
    "utmContent": "",
    "referrer": "https://google.com/",
    "landingPage": "https://app.example.com/",
    "source": "sdk",
    "ip": "203.0.113.7",
    "startedAt": "2026-04-20 09:00:00.000",
    "createdAt": "2026-04-20 09:00:00.000"
  }],
  "totalCount": 87,
  "page": 1,
  "perPage": 50
}

GET

https://api.sumidata.io/api/partner/schema/validateGET /api/partner/schema/validate

Checks the 200 most recently ingested events against the event metadata allowlist - the category, surface and feature stored for each event name. No query params.

Example request

curl

curl "https://api.sumidata.io/api/partner/schema/validate" \
  -H "Authorization: Bearer sumi_…"

Success · 200 OK

response.json

{
  "valid": false,
  "checked": 200,
  "violations": [{
    "eventId": "8b1f4e2a-…",
    "field": "feature",  // "category" | "surface" | "feature"
    "value": "Checkout-Start",
    "rule": "Feature must be lowercase alphanumeric and underscores only"
  }]
}

With no events yet the response is { "valid": true, "checked": 0, "violations": [], "message": "No events ingested yet — nothing to validate." }.

Errors

401	`Valid API token required. Use Authorization: Bearer sumi_xxx`	Missing `Authorization` header, or it does not start with `Bearer sumi_`
401	`Invalid or revoked API token`	Token not found, or revoked

04AI-agent quick reference

A tight, machine-readable surface for agents that read your Sumidata data autonomously.

For agents building reports or answering questions from Sumidata data, the recipe is short: one bearer token, one base URL, one query DSL.

agent.yaml

api:
  base_url: https://api.sumidata.io
  auth: Bearer {SUMIDATA_TOKEN}
  scope: read-only (events, logs, sessions, health, schema validation)

endpoints:
  - path: /api/partner/health
    use: connectivity + last-event watchdog
  - path: /api/partner/events
    use: list events (conversions have orderId != "")
  - path: /api/partner/logs
    use: filterable log tail
  - path: /api/partner/sessions
    use: UTM-annotated session list
  - path: /api/partner/schema/validate
    use: metadata allowlist check on the last 200 events

filter_dsl:
  shape: q[field__action]=value
  actions: [eq, not, in, cont, like, gte, lte, is, order]
  pagination: q[page], q[perPage] (1–200, default 50)

write_path:
  endpoint: POST /sdk/ingest
  auth: projectId in body (not Bearer)
  docs: /docs/conversions/server-ingest