Sumidatasumidata.io
Sign in
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_live_…
Content-Typeapplication/json
ScopeRead-only — no event ingest here
i
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. 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.

Filter actions

ActionSQLExample
__eq= valueq[level__eq]=error
__not!= valueq[source__not]=sdk
__inIN (...)q[level__in]=error,warn
__likeILIKE '%v%'q[name__like]=page
__gte>= valueq[timestamp__gte]=2026-01-01
__lte<= valueq[timestamp__lte]=2026-04-01
__isIS NULLq[sessionId__is]=null
__orderORDER BYq[timestamp__order]=desc

Pagination

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

03Endpoints

Four endpoints — health, events, logs, sessions. 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_live_…"

Success · 200 OK

response.json
{
  "status": "healthy",  // "healthy" | "warning" | "error"
  "projectId": "proj_…",
  "lastEventAt": "2026-04-20T09:12:44Z",
  "lastLogAt": "2026-04-20T09:10:02Z",
  "eventsLastHour": 142,
  "logsLastHour": 58,
  "sessionsLastHour": 23
}
i
status is healthy when the last event arrived within 5 min, warning within 60 min, error otherwise (or if no events exist yet).

Errors

401invalid_tokenMissing or malformed Authorization header
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

NameTypeRequiredDescription
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[perPage]int—1–200. Default 50

Example request

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

Success · 200 OK

response.json
{
  "events": [
    {
      "id": "evt_01HW…",
      "name": "purchase",
      "payload": "{…}",  // JSON string
      "sessionId": "…",
      "externalUserId": "user_7e2a9c",
      "timestamp": "2026-04-20T09:12:44.000Z",
      "url": "https://app.example.com/checkout",
      "platform": "Linux",
      "browser": "Chrome",
      "source": "sdk"
    }
  ],
  "totalCount": 1432,
  "page": 1,
  "perPage": 50
}
i
Conversion fields (orderId, totalAmount, productId, utmSource…) are columns on the same row, not inside payload. Request them explicitly via q[orderId__not]= to list 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

400invalid_qUnknown column in q[…] or invalid action suffix
401invalid_tokenMissing or malformed token
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

NameTypeRequiredDescription
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

Example request

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

Success · 200 OK

response.json
{
  "logs": [{
    "id": "log_…",
    "level": "error",
    "message": "Checkout failed: invalid token",
    "source": "sdk",
    "sessionId": "…",
    "timestamp": "2026-04-20T09:12:44.000Z",
    "url": "https://app.example.com/checkout"
  }],
  "totalCount": 39,
  "page": 1,
  "perPage": 50
}
GET

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

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

Query parameters

NameTypeRequiredDescription
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[source__eq]string—sdk, backend, or import
q[createdAt__gte]ISO-8601—Session start lower bound

Example request

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

Success · 200 OK

response.json
{
  "sessions": [{
    "id": "ses_…",
    "deviceId": "…",
    "externalUserId": "user_7e2a9c",
    "platform": "Linux",
    "browser": "Chrome",
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "spring-2026",
    "referrer": "https://google.com/",
    "landingPage": "https://app.example.com/",
    "source": "sdk",
    "startedAt": "2026-04-20T09:00:00.000Z",
    "createdAt": "2026-04-20T09:00:00.000Z"
  }],
  "totalCount": 87,
  "page": 1,
  "perPage": 50
}

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)

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

filter_dsl:
  shape: q[field__action]=value
  actions: [eq, not, in, 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