Ingest server-side pageview REST API

POST

/api/ingest/server/pageview

curl --request POST \
  --url https://app.hitkeep.com/api/ingest/server/pageview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "dnt": true, "language": "example", "page_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "referrer": "example", "screen_height": 1, "screen_width": 1, "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "timestamp": "2026-04-15T12:00:00Z", "url": "https://example.com", "user_agent": "example", "viewport_height": 1, "viewport_width": 1, "visitor_ip": "example" }'

Accepts one trusted server-side pageview from an API client. Use this endpoint for backend forwarding, CMS plugins, reverse proxy forwarding, edge workers, and historical pageview replay. It does not require browser Origin or Referer headers. HitKeep resolves the site from the submitted URL hostname, requires site.manage_data for that resolved site, and uses visitor_ip for ingest-time exclusions, spam filtering, and country, region, city, provider, and ASN lookup. UTM values and hk_qr QR attribution are read from the query string in url, for example utm_source, utm_campaign, and hk_qr on the visitor-facing URL, not from top-level JSON fields. Stored analytics records contain derived country, region, city, provider, and ASN context. HitKeep does not store the raw visitor IP. This endpoint uses the ingest rate limiter.

Authorizations

• bearerAuth
• apiKeyAuth

Request Body^required

Media typeapplication/json

object

dnt

When true, HitKeep drops the record consistently with browser tracker privacy behavior.

boolean

language

string

page_id

Optional page identifier. Generated when omitted.

string format: uuid

referrer

string

screen_height

integer

screen_width

integer

session_id

Optional visitor grouping key. If omitted, this record gets its own standalone session.

string format: uuid

timestamp

required

Canonical analytics time in RFC3339 format.

string format: date-time

url

required

Absolute page URL. The hostname resolves the configured HitKeep site. UTM values and hk_qr QR attribution are read from this URL query string.

string format: uri

user_agent

required

User agent from the original visitor request context.

string

viewport_height

integer

viewport_width

integer

visitor_ip

required

Trusted transient visitor IP context. Used to derive country, region, city, provider, and ASN metadata. HitKeep does not store the raw visitor IP.

string format: ip

Example^generated

{
  "dnt": true,
  "language": "example",
  "page_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "referrer": "example",
  "screen_height": 1,
  "screen_width": 1,
  "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "timestamp": "2026-04-15T12:00:00Z",
  "url": "https://example.com",
  "user_agent": "example",
  "viewport_height": 1,
  "viewport_width": 1,
  "visitor_ip": "example"
}

Responses

202

Accepted. Empty response body.

400

Invalid request

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}

401

Unauthorized

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}

403

Access denied

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}

404

Site not found

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}

429

Too many requests

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}

503

Service not available

Media typeapplication/json

object

message

string

Example^generated

{
  "message": "example"
}