API docs by Redocly

Pyxis API (1)

Download OpenAPI specification:

License: MIT

Privacy-first product analytics: event ingestion, dashboard queries and erasure of a user's events. No cookies on tracked visitors, no personal data, no IP address or user agent stored.

health

Liveness check of the API

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

dashboard sign-in

Revoke the session of the pyxis_session cookie

Authorizations:
pyxis_session

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "status_code": -9007199254740991
}

Revoke every session of the signed-in admin, this one included

Signs the admin out of every device at once. Needs a live session.

Authorizations:
pyxis_session

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "status_code": -9007199254740991
}

Email a sign-in code

Always answers 202: a code is created and emailed only when the email belongs to an admin.

Request Body schema: application/json
required
email
required
string <email> <= 254 characters ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-...
locale
string <= 35 characters ^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$

The language of the dashboard asking, as a BCP 47 tag (en, pt-BR). The email is written in it when the API has it (matched on the language, so pt-PT gets pt-BR), else in English.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "locale": "string"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "status_code": -9007199254740991
}

Exchange a sign-in code for a session token

The session records the browser, system and device type classified from the request, for the sessions list; the user agent itself is never kept.

Request Body schema: application/json
required
code
required
string^\d{6}$
email
required
string <email> <= 254 characters ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-...

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "email": "user@example.com",
  • "session_token": "string"
}

The signed-in admin and their projects

Authorizations:
pyxis_session

Responses

Response samples

Content type
application/json
{
  • "email": "user@example.com",
  • "projects": [
    ]
}

The live sessions of the signed-in admin, this one marked

Authorizations:
pyxis_session

Responses

Response samples

Content type
application/json
{
  • "sessions": [
    ]
}

End one session of the signed-in admin, this one included

Authorizations:
pyxis_session
path Parameters
sessionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "status_code": -9007199254740991
}

ingestion

CORS preflight for the batch route

Responses

Ingest a batch of events from the browser

Public route, authenticated by the project key in the body and the Origin header. Invalid events are counted as rejected; the rest of the batch is stored. A resent event is a duplicate, never stored twice.

Request Body schema:
required
required
Array of objects (IncomingEvent) [ 1 .. 50 ] items
key
required
string^pyxis_pk_[A-Za-z0-9]{32}$
sent_at
required
string <date-time> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...

Responses

Request samples

Content type
{
  • "events": [
    ],
  • "key": "string",
  • "sent_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "accepted": 0,
  • "duplicates": 0,
  • "rejected": 0
}

dashboard queries

Visits per day and channel, and the sources that brought them

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

Responses

Response samples

Content type
application/json
{
  • "campaigns": [
    ],
  • "days": [
    ],
  • "sources": [
    ]
}

Visits and conversions by device type, browser, system, country and region

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

Responses

Response samples

Content type
application/json
{
  • "browsers": [
    ],
  • "countries": [
    ],
  • "device_types": [
    ],
  • "operating_systems": [
    ],
  • "regions": [
    ]
}

Entry and exit pages, single-page visits and visit length

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

Responses

Response samples

Content type
application/json
{
  • "entry_pages": [
    ],
  • "exit_pages": [
    ],
  • "median_visit_seconds": -9007199254740991,
  • "single_page_visits": -9007199254740991,
  • "visit_lengths": [
    ],
  • "visits": -9007199254740991
}

The most used named events or screens, with their daily counts

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

kind
required
string
Enum: "events" "screens"

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

How the property values of one named event break down

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

name
required
string^[a-z][a-z0-9_]{0,63}$

The named event to break down

Responses

Response samples

Content type
application/json
{
  • "events": -9007199254740991,
  • "keys": [
    ],
  • "name": "string"
}

How many visits or people reached each step of a funnel, in order

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

mode
required
string
Enum: "visit" "user"
steps
required
string

URL-encoded JSON array of 2 to 8 steps: {"type":"page","path":"/calculator-*"} (a star matches any characters) or {"type":"event","name":"signup_completed"}

Responses

Response samples

Content type
application/json
{
  • "median_seconds_overall": -9007199254740991,
  • "steps": [
    ]
}

A funnel per device type or channel of the visit

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

steps
required
string

The steps of the funnel, as for /funnel

by
required
string
Enum: "device" "channel"

Responses

Response samples

Content type
application/json
{
  • "by": "device",
  • "segments": [
    ]
}

The visits or people who reached, or dropped at, one funnel step

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

mode
required
string
Enum: "visit" "user"
steps
required
string

The steps of the funnel, as for /funnel

step
required
integer >= 1

The step, 1 for the first; dropped needs 2 or more

outcome
required
string
Enum: "reached" "dropped"
cursor
string

The next_cursor of the previous page

Responses

Response samples

Content type
application/json
{
  • "next_cursor": "string",
  • "subjects": [
    ]
}

The icon of the project's site

Taken from the first allowed origin once a day: the touch icon or the largest icon the home page declares, else /favicon.ico; raster images only, up to 100 KB. Cache it by adding icon_version from GET /v1/me to the URL.

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "status_code": -9007199254740991
}

KPIs, daily activity, top pages and top events of a range

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

Responses

Response samples

Content type
application/json
{
  • "comparison_cutoff": "string",
  • "days": [
    ],
  • "kpis": {
    },
  • "previous_days": [
    ],
  • "top_events": [
    ],
  • "top_pages": [
    ]
}

Writes, or failed reads, per route: failures, statuses, durations and screens

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

screen
string

Only the calls made from this page path

kind
string
Enum: "writes" "reads"

writes (the default): every non-GET call; reads: failed GET calls only

route
string

Also answer route_days for this method and route: POST /orders/:id

Responses

Response samples

Content type
application/json
{
  • "days": [
    ],
  • "kind": "writes",
  • "route_days": [
    ],
  • "routes": [
    ]
}

The settings of the project, its live keys and its activity

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "allowed_origins": [
    ],
  • "conversion_event": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "event_retention_months": -9007199254740991,
  • "first_event_at": "2019-08-24T14:15:22Z",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "last_event_at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "public_keys": [
    ],
  • "secret_keys": [
    ],
  • "timezone": "string"
}

The visits of the range by the weekday and local hour they started

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

Responses

Response samples

Content type
application/json
{
  • "weekdays": [
    ]
}

The visits of a person or of one visit, with every event

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
before
string <date-time>

The next_before of the previous page

session_id
string <uuid>
user_id
string

Responses

Response samples

Content type
application/json
{
  • "next_before": "2019-08-24T14:15:22Z",
  • "visits": [
    ]
}

The visits of a range, newest first, filtered by what they did

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
query Parameters
from
required
string <date>

First day, inclusive, in the project time zone

to
required
string <date>

Last day, inclusive, at most today in the project time zone; 400 days at most

path
Array of strings <= 3 items

A page the visit viewed; a star matches any characters. Repeat it, up to 3 times, for visits that viewed every one

event
string

A named event the visit sent

property
string

key=value: the event above carried this property value; needs event

channel
string
Enum: "paid" "email" "social" "campaign" "organic" "referral" "direct"
device
string
Enum: "mobile" "tablet" "desktop" "other"
identity
string
Enum: "identified" "anonymous"
country
string^[A-Z]{2}$

The two-letter country code of the visit

region
string^[A-Z]{2}-[A-Z0-9]{1,3}$

The region of the visit: its ISO 3166-2 code, the country code, a hyphen and the subdivision

source
string <= 128 characters

The source of the visit as Acquisition names it: campaign source, referring host or (direct)

campaign
string <= 64 characters

The campaign (utm_campaign) of the visit entry

route
string

A request the visit made, as method and route: POST /orders/:id

failed
string
Enum: "true" "false"

true: the visit had a failed request (status 0 or 400 and above); with route, on that route

cursor
string

The next_cursor of the previous page

Responses

Response samples

Content type
application/json
{
  • "next_cursor": "string",
  • "total": -9007199254740991,
  • "visits": [
    ]
}

dashboard preferences

The e-mails the signed-in admin receives about the project

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "weekly_digest": true
}

Choose the e-mails the signed-in admin receives about the project

Changes only the signed-in admin, for this project only.

Authorizations:
pyxis_session
path Parameters
projectId
required
string <uuid>
Request Body schema: application/json
required
weekly_digest
required
boolean

Whether the admin receives the weekly digest of this project, sent on Mondays with the week that closed on Sunday in the project time zone

Responses

Request samples

Content type
application/json
{
  • "weekly_digest": true
}

Response samples

Content type
application/json
{
  • "weekly_digest": true
}

subjects

Erase every event about a user, the visit they signed up in included

Authorizations:
secret_key
path Parameters
userId
required
string

The user id the site sent to identify

Responses

Response samples

Content type
application/json
{
  • "deleted_events": -9007199254740991
}

Export every event about a user, for a data access request

Authorizations:
secret_key
path Parameters
userId
required
string

The user id the site sent to identify

query Parameters
after
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "next_after": "ee4ed11a-6422-4013-aa47-bf6402edc672"
}