Ingest server-side event

POST

/api/ingest/server/event

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

Accepts one trusted server-side custom event from an API client. This server-to-server endpoint 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 and spam filtering. Stored analytics records contain derived context instead of the visitor IP. This endpoint uses the ingest rate limiter.

Authorizations

• bearerAuth
• apiKeyAuth

Request Body ^required

Media type application/json

object

dnt

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

boolean

name

required

Custom event name.

string

properties

object

key

additional properties

any

referrer

string

session_id

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

string format: uuid

timestamp

required

Canonical analytics time in RFC3339 format.

string format: date-time

url

required

Absolute page or event context URL. The hostname resolves the configured HitKeep site.

string format: uri

user_agent

required

User agent from the original visitor request context.

string

visitor_ip

required

Trusted transient visitor IP context. Used for filtering and enrichment, then discarded.

string format: ip

Example ^generated

{
  "dnt": true,
  "name": "example",
  "properties": {},
  "referrer": "example",
  "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "timestamp": "2026-04-15T12:00:00Z",
  "url": "https://example.com",
  "user_agent": "example",
  "visitor_ip": "example"
}

Responses

202

Accepted. Empty response body.

400

Invalid request

Media type application/json

object

message

string

Example ^generated

{
  "message": "example"
}

401

Unauthorized

Media type application/json

object

message

string

Example ^generated

{
  "message": "example"
}

403

Access denied

Media type application/json

object

message

string

Example ^generated

{
  "message": "example"
}

404

Site not found

Media type application/json

object

message

string

Example ^generated

{
  "message": "example"
}

429

Too many requests

Media type application/json

object

message

string

Example ^generated

{
  "message": "example"
}

503

Service not available

Media type application/json

object

message

string

Example ^generated

{
  "message": "example"
}