RESTful API for sending page views, events, and session data to Pirsch, and for querying statistics including visitors, pages, referrers, UTM parameters, geo-location, device, browser, conversion goals, funnels, and real-time active visitors. Also exposes management endpoints for domains, members, clients, webhooks, email reports, traffic filters, short links, and views.
openapi: 3.0.3
info:
title: Pirsch API
description: >-
RESTful API for sending page views, events, and session data to Pirsch,
and for querying statistics including visitors, pages, referrers, UTM
parameters, geo-location, device, browser, conversion goals, funnels,
and real-time active visitors. Also exposes management endpoints for
domains, members, clients, webhooks, email reports, traffic filters,
short links, and views.
version: "1"
contact:
name: Pirsch Support
url: https://pirsch.io
license:
name: Proprietary
url: https://pirsch.io/privacy
servers:
- url: https://api.pirsch.io/api/v1
description: Pirsch production API
security:
- BearerAuth: []
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Pass an OAuth2 access token obtained from POST /token, or a static
access key, as a Bearer token in the Authorization header.
schemas:
TokenRequest:
type: object
required:
- client_id
- client_secret
properties:
client_id:
type: string
description: OAuth2 client ID
client_secret:
type: string
description: OAuth2 client secret
TokenResponse:
type: object
properties:
access_token:
type: string
description: Bearer token to use in subsequent requests
expires_at:
type: string
format: date-time
description: UTC timestamp when the token expires
HitRequest:
type: object
required:
- url
- ip
- user_agent
properties:
url:
type: string
format: uri
description: Full URL of the page viewed
ip:
type: string
description: Visitor IP address
user_agent:
type: string
description: Visitor User-Agent header value
accept_language:
type: string
description: Accept-Language header value
referrer:
type: string
description: HTTP Referer header value
title:
type: string
description: Page title
sec_ch_ua:
type: string
description: Sec-CH-UA client hint header
sec_ch_ua_mobile:
type: string
description: Sec-CH-UA-Mobile client hint header
sec_ch_ua_platform:
type: string
description: Sec-CH-UA-Platform client hint header
sec_ch_ua_platform_version:
type: string
description: Sec-CH-UA-Platform-Version client hint header
sec_ch_width:
type: string
description: Sec-CH-Width client hint header
sec_ch_viewport_width:
type: string
description: Sec-CH-Viewport-Width client hint header
screen_width:
type: integer
description: Screen width in pixels
screen_height:
type: integer
description: Screen height in pixels
disable_bot_filter:
type: boolean
description: Disable bot filtering for this request
tags:
type: object
additionalProperties:
type: string
description: Custom key-value tags
HitBatchRequest:
type: object
allOf:
- $ref: '#/components/schemas/HitRequest'
- type: object
required:
- time
properties:
time:
type: string
format: date-time
description: Timestamp of the page view (ISO 8601)
EventRequest:
type: object
allOf:
- $ref: '#/components/schemas/HitRequest'
- type: object
required:
- event_name
properties:
event_name:
type: string
description: Name of the event
event_duration:
type: number
description: Event duration in seconds
event_meta:
type: object
additionalProperties:
type: string
description: Event metadata key-value pairs
non_interactive:
type: boolean
description: Whether the event is non-interactive
EventBatchRequest:
type: object
allOf:
- $ref: '#/components/schemas/EventRequest'
- type: object
required:
- time
properties:
time:
type: string
format: date-time
SessionRequest:
type: object
required:
- ip
- user_agent
properties:
ip:
type: string
user_agent:
type: string
sec_ch_ua:
type: string
sec_ch_ua_mobile:
type: string
sec_ch_ua_platform:
type: string
sec_ch_ua_platform_version:
type: string
disable_bot_filter:
type: boolean
SessionBatchRequest:
type: object
allOf:
- $ref: '#/components/schemas/SessionRequest'
- type: object
required:
- time
properties:
time:
type: string
format: date-time
TotalStats:
type: object
properties:
visitors:
type: integer
views:
type: integer
sessions:
type: integer
bounces:
type: integer
bounce_rate:
type: number
format: float
cr:
type: number
format: float
custom_metric_avg:
type: number
format: float
custom_metric_total:
type: number
format: float
VisitorStats:
type: object
properties:
day:
type: string
format: date-time
week:
type: string
format: date-time
month:
type: string
format: date-time
year:
type: string
format: date-time
visitors:
type: integer
views:
type: integer
sessions:
type: integer
bounces:
type: integer
bounce_rate:
type: number
format: float
cr:
type: number
format: float
custom_metric_avg:
type: number
format: float
custom_metric_total:
type: number
format: float
PageStats:
type: object
properties:
path:
type: string
title:
type: string
visitors:
type: integer
views:
type: integer
sessions:
type: integer
bounces:
type: integer
relative_visitors:
type: number
format: float
relative_views:
type: number
format: float
bounce_rate:
type: number
format: float
average_time_spent_seconds:
type: integer
ReferrerStats:
type: object
properties:
referrer:
type: string
referrer_name:
type: string
referrer_icon:
type: string
visitors:
type: integer
sessions:
type: integer
relative_visitors:
type: number
format: float
bounces:
type: integer
bounce_rate:
type: number
format: float
PlatformStats:
type: object
properties:
platform_desktop:
type: integer
platform_mobile:
type: integer
platform_unknown:
type: integer
relative_platform_desktop:
type: number
format: float
relative_platform_mobile:
type: number
format: float
relative_platform_unknown:
type: number
format: float
EventStats:
type: object
properties:
name:
type: string
count:
type: integer
visitors:
type: integer
views:
type: integer
cr:
type: number
format: float
average_duration_seconds:
type: integer
meta_keys:
type: array
items:
type: string
ActiveVisitors:
type: object
properties:
stats:
type: array
items:
type: object
countries:
type: array
items:
type: object
visitors:
type: integer
Domain:
type: object
properties:
id:
type: string
hostname:
type: string
subdomain:
type: string
def_time:
type: string
format: date-time
mod_time:
type: string
format: date-time
user_id:
type: string
nullable: true
organization_id:
type: string
nullable: true
timezone:
type: string
public:
type: boolean
disable_scripts:
type: boolean
subscription_active:
type: boolean
display_name:
type: string
group_by_title:
type: boolean
user_role:
type: string
enum:
- Owner
- Admin
- Viewer
theme_id:
type: string
settings:
type: object
CreateDomainRequest:
type: object
required:
- hostname
- subdomain
- timezone
properties:
hostname:
type: string
subdomain:
type: string
timezone:
type: string
organization_id:
type: string
theme_id:
type: string
public:
type: boolean
group_by_title:
type: boolean
disable_scripts:
type: boolean
display_name:
type: string
settings:
type: object
Member:
type: object
properties:
id:
type: string
role:
type: string
enum:
- Owner
- Admin
- Viewer
user_id:
type: string
user:
type: object
InviteMembersRequest:
type: object
properties:
id:
type: string
description: Domain ID
organization_id:
type: string
emails:
type: array
items:
type: string
format: email
UpdateMemberRequest:
type: object
required:
- id
- role
properties:
id:
type: string
description: Member ID
role:
type: string
enum:
- Viewer
- Admin
Invitation:
type: object
properties:
id:
type: string
email:
type: string
format: email
domain:
type: object
organization:
type: object
AccessLink:
type: object
properties:
id:
type: string
code:
type: string
description:
type: string
valid_until:
type: string
format: date-time
nullable: true
CreateAccessLinkRequest:
type: object
required:
- domain_id
properties:
domain_id:
type: string
description:
type: string
valid_until:
type: string
format: date-time
UpdateAccessLinkRequest:
type: object
required:
- id
properties:
id:
type: string
description:
type: string
valid_until:
type: string
format: date-time
ConversionGoal:
type: object
properties:
id:
type: string
domain_id:
type: string
name:
type: string
path_pattern:
type: string
pattern:
type: string
event_name:
type: string
event_meta_key:
type: string
event_meta_value:
type: string
custom_metric_key:
type: string
custom_metric_type:
type: string
delete_reached:
type: boolean
email_reached:
type: boolean
CreateGoalRequest:
type: object
required:
- domain_id
- name
properties:
domain_id:
type: string
name:
type: string
path_pattern:
type: string
event_name:
type: string
event_meta_key:
type: string
event_meta_value:
type: string
custom_metric_key:
type: string
custom_metric_type:
type: string
delete_reached:
type: boolean
email_reached:
type: boolean
UpdateGoalRequest:
type: object
allOf:
- $ref: '#/components/schemas/CreateGoalRequest'
- type: object
required:
- id
properties:
id:
type: string
Funnel:
type: object
properties:
id:
type: string
domain_id:
type: string
name:
type: string
steps:
type: array
items:
type: object
properties:
name:
type: string
filter:
type: object
CreateFunnelRequest:
type: object
required:
- domain_id
- name
- steps
properties:
domain_id:
type: string
id:
type: string
name:
type: string
steps:
type: array
items:
type: object
properties:
name:
type: string
filter:
type: object
ShortLink:
type: object
properties:
id:
type: string
domain_id:
type: string
name:
type: string
event_name:
type: string
utm_source:
type: string
utm_medium:
type: string
utm_campaign:
type: string
utm_content:
type: string
utm_term:
type: string
expires_at:
type: string
format: date-time
nullable: true
expired_url:
type: string
webhook_id:
type: string
tags:
type: array
items:
type: string
urls:
type: array
items:
type: object
CreateShortLinkRequest:
type: object
required:
- domain_id
- name
properties:
domain_id:
type: string
id:
type: string
name:
type: string
event_name:
type: string
utm_source:
type: string
utm_medium:
type: string
utm_campaign:
type: string
utm_content:
type: string
utm_term:
type: string
expires_at:
type: string
format: date-time
expired_url:
type: string
password:
type: string
webhook_endpoint:
type: string
title:
type: string
description:
type: string
image:
type: string
allow_indexing:
type: boolean
tags:
type: array
items:
type: string
urls:
type: array
items:
type: object
EmailReport:
type: object
properties:
id:
type: string
domain_id:
type: string
emails:
type: array
items:
type: string
format: email
interval:
type: integer
link_to:
type: string
next_report:
type: string
format: date-time
reply_to:
type: string
format: email
CreateReportRequest:
type: object
required:
- domain_id
- emails
- interval
properties:
domain_id:
type: string
emails:
type: array
items:
type: string
format: email
interval:
type: integer
description: 0 for monthly, or number of weeks
reply_to:
type: string
format: email
start_date:
type: string
format: date
link_to:
type: string
Webhook:
type: object
properties:
id:
type: string
domain_id:
type: string
description:
type: string
event:
type: string
endpoint:
type: string
format: uri
active:
type: boolean
CreateWebhookRequest:
type: object
required:
- domain_id
- event
- endpoint
properties:
id:
type: string
domain_id:
type: string
description:
type: string
event:
type: string
endpoint:
type: string
format: uri
TrafficFilter:
type: object
properties:
id:
type: string
domain_id:
type: string
type:
type: string
description:
type: string
filter:
type: string
CreateFilterRequest:
type: object
required:
- domain_id
- type
- filter
properties:
id:
type: string
domain_id:
type: string
type:
type: string
description:
type: string
filter:
type: string
View:
type: object
properties:
id:
type: string
domain_id:
type: string
name:
type: string
from:
type: string
format: date
to:
type: string
format: date
period:
type: string
CreateViewRequest:
type: object
required:
- domain_id
- name
properties:
domain_id:
type: string
id:
type: string
name:
type: string
from:
type: string
format: date
to:
type: string
format: date
period:
type: string
Client:
type: object
properties:
client_id:
type: string
description:
type: string
client_secret:
type: string
description: Only returned on creation
CreateClientRequest:
type: object
required:
- domain_id
- type
- description
properties:
domain_id:
type: string
type:
type: string
enum:
- oauth
- token
description:
type: string
AlternativeDomain:
type: object
properties:
id:
type: string
domain_id:
type: string
hostname:
type: string
ErrorResponse:
type: object
properties:
validation:
type: object
additionalProperties:
type: array
items:
type: string
description: Field-level validation errors
error:
type: array
items:
type: string
description: General error messages
context:
type: object
additionalProperties: true
description: Additional error context
StatisticsQueryParams:
description: Common statistics query parameters
type: object
paths:
/token:
post:
operationId: getToken
summary: Obtain access token
description: Authenticate with client credentials to obtain a Bearer access token
security: []
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRequest'
responses:
'200':
description: Access token returned
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'400':
description: Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/hit:
post:
operationId: sendPageView
summary: Send a page view
description: Track a single page view for a domain
tags:
- Tracking
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/HitRequest'
responses:
'200':
description: Page view accepted
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/hit/batch:
post:
operationId: sendPageViewBatch
summary: Send multiple page views
description: Track a batch of page views
tags:
- Tracking
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/HitBatchRequest'
responses:
'200':
description: Batch accepted
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/event:
post:
operationId: sendEvent
summary: Send a custom event
description: Track a single custom event with optional metadata
tags:
- Tracking
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EventRequest'
responses:
'200':
description: Event accepted
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/event/batch:
post:
operationId: sendEventBatch
summary: Send multiple custom events
description: Track a batch of custom events
tags:
- Tracking
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EventBatchRequest'
responses:
'200':
description: Batch accepted
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/session:
post:
operationId: keepSessionAlive
summary: Keep a session alive
description: Extend an existing visitor session
tags:
- Tracking
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SessionRequest'
responses:
'200':
description: Session extended
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/session/batch:
post:
operationId: keepSessionAliveBatch
summary: Keep multiple sessions alive
description: Extend multiple visitor sessions in a single request
tags:
- Tracking
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SessionBatchRequest'
responses:
'200':
description: Sessions extended
/statistics/total:
get:
operationId: getTotalStatistics
summary: Get total statistics
description: Get total visitors, views, sessions, and bounce data for a date range
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
description: Domain ID
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
- name: tz
in: query
schema:
type: string
- name: scale
in: query
schema:
type: string
enum:
- day
- week
- month
- year
responses:
'200':
description: Total statistics
content:
application/json:
schema:
$ref: '#/components/schemas/TotalStats'
/statistics/visitor:
get:
operationId: getVisitorStatistics
summary: Get visitor statistics over time
description: Get visitors grouped by time scale
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
- name: tz
in: query
schema:
type: string
- name: scale
in: query
schema:
type: string
enum:
- day
- week
- month
- year
responses:
'200':
description: Visitor time series
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VisitorStats'
/statistics/page:
get:
operationId: getPageStatistics
summary: Get page statistics
description: Get statistics broken down by page path
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
- name: search
in: query
schema:
type: string
- name: offset
in: query
schema:
type: integer
- name: limit
in: query
schema:
type: integer
- name: sort
in: query
schema:
type: string
- name: direction
in: query
schema:
type: string
enum:
- asc
- desc
responses:
'200':
description: Page statistics
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PageStats'
/statistics/hostname:
get:
operationId: getHostnameStatistics
summary: Get hostname statistics
description: Get statistics broken down by hostname
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Hostname statistics
content:
application/json:
schema:
type: array
items:
type: object
properties:
hostname:
type: string
visitors:
type: integer
views:
type: integer
sessions:
type: integer
bounces:
type: integer
relative_visitors:
type: number
relative_views:
type: number
bounce_rate:
type: number
/statistics/referrer:
get:
operationId: getReferrerStatistics
summary: Get referrer statistics
description: Get statistics broken down by referrer
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
- name: offset
in: query
schema:
type: integer
- name: limit
in: query
schema:
type: integer
responses:
'200':
description: Referrer statistics
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ReferrerStats'
/statistics/channel:
get:
operationId: getChannelStatistics
summary: Get traffic channel statistics
description: Get statistics grouped by traffic channel
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Channel statistics
content:
application/json:
schema:
type: array
items:
type: object
/statistics/utm/source:
get:
operationId: getUtmSourceStatistics
summary: Get UTM source statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: UTM source breakdown
content:
application/json:
schema:
type: array
items:
type: object
/statistics/utm/medium:
get:
operationId: getUtmMediumStatistics
summary: Get UTM medium statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pirsch/refs/heads/main/openapi/pirsch-pirsch-api-openapi.yml