API Reference

Base URL: https://app.vibeping.dev

POST /api/v1/event

Ingest events. This is what the SDK calls under the hood. You can also call it directly if you want to send events from a backend or custom client.

Request

curl -X POST https://app.vibeping.dev/api/v1/event \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "vp_abc123",
    "events": [
      {
        "type": "custom",
        "name": "server_deploy",
        "url": "https://myapp.com",
        "properties": {
          "version": "1.2.0",
          "environment": "production"
        }
      }
    ]
  }'

Body

Field	Type	Required	Description
`apiKey`	`string`	Yes	Your project API key
`events`	`array`	Yes	Array of event objects (max 100 per request)

You can also pass the API key via the x-api-key header or ?api_key= query param instead of the body.

Event Object

Field	Type	Required	Description
`type`	`string`	Yes	One of: `pageview`, `error`, `vital`, `custom`, `session`, `identify`
`name`	`string`	No	Event name (for `custom` and `vital` types)
`url`	`string`	No	Page URL
`referrer`	`string`	No	Referrer URL
`title`	`string`	No	Page title
`properties`	`object`	No	Arbitrary key-value data
`sessionId`	`string`	No	Session identifier
`screenWidth`	`number`	No	Viewport width
`screenHeight`	`number`	No	Viewport height
`language`	`string`	No	Browser language
`browser`	`string`	No	Browser name
`os`	`string`	No	Operating system
`timestamp`	`number`	No	Unix timestamp in ms. Defaults to server time

Response

Success (200):

{
  "success": true,
  "accepted": 1
}

Errors:

Status	Body	Cause
401	`{ "error": "Missing or invalid api_key" }`	No API key provided
401	`{ "error": "Invalid API key" }`	API key doesn't match any project
400	`{ "error": "events array is required and must not be empty" }`	Missing or empty events
400	`{ "error": "Maximum 100 events per request" }`	Too many events in one batch
400	`{ "error": "No valid events in payload" }`	All events had invalid types

CORS

The endpoint accepts requests from any origin (Access-Control-Allow-Origin: *). This is intentional — the SDK runs on your users' browsers.

GET /api/v1/stats

Fetch aggregated stats for a project. Requires authentication.

Request

curl "https://app.vibeping.dev/api/v1/stats?project_id=YOUR_PROJECT_ID&period=7d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Query Parameters

Param	Required	Default	Description
`project_id`	Yes	—	Your project UUID
`period`	No	`7d`	Time range: `1h`, `24h`, `7d`, `30d`, `90d`

Authentication

Pass a Supabase access token in the Authorization: Bearer <token> header. The API verifies that the authenticated user owns the project.

Response (200)

{
  "period": "7d",
  "since": "2026-03-27T22:00:00.000Z",
  "totalPageviews": 1423,
  "uniqueSessions": 312,
  "errorCount": 7,
  "topPages": [
    { "path": "/", "views": 580 },
    { "path": "/pricing", "views": 234 },
    { "path": "/dashboard", "views": 189 }
  ],
  "topReferrers": [
    { "referrer": "(direct)", "count": 420 },
    { "referrer": "https://google.com", "count": 198 }
  ],
  "avgVitals": {
    "LCP": 1.82,
    "CLS": 0.04,
    "INP": 120,
    "TTFB": 380
  },
  "totalEvents": 2891
}

Errors

Status	Cause
400	Missing `project_id` or invalid `period`
401	Missing or invalid auth token
404	Project not found or user doesn't have access