API Reference

REST API reference for the Kitbase SDK endpoints.

Base URL

https://api.kitbase.dev

Authentication

SDK endpoints use the x-sdk-key header:

x-sdk-key: <YOUR_SDK_KEY>

---

Events

Track Event

Track an event in your application.

POST /sdk/v1/logs

Headers

Header	Required	Description
x-sdk-key	Yes	Your Kitbase SDK key
Content-Type	Yes	application/json

Request Body

{
  "event": "New Subscription",
  "channel": "payments",
  "user_id": "user-123",
  "anonymous_id": "550e8400-e29b-41d4-a716-446655440000",
  "icon": "💰",
  "notify": true,
  "description": "User subscribed to premium plan",
  "timestamp": 1705321800000,
  "tags": {
    "plan": "premium",
    "amount": 9.99
  }
}

Parameters

Field	Type	Required	Description
event	string	Yes	Event name
channel	string	Yes	Event channel/category
user_id	string	No	Identified user ID
anonymous_id	string	No	Anonymous user ID (UUID)
icon	string	No	Emoji icon
notify	boolean	No	Send real-time notification
description	string	No	Event description
timestamp	number	No	Unix timestamp in ms
tags	object	No	Key-value metadata

Response

Status: 202 Accepted

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "New Subscription",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Errors

Status	Description
400	Invalid parameters
401	Invalid SDK key
503	Queue full

---

Identify User

Link an anonymous user to an identified user.

POST /sdk/v1/identify

Request Body

{
  "anonymous_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user-123",
  "traits": {
    "email": "user@example.com",
    "plan": "premium"
  }
}

Parameters

Field	Type	Required	Description
anonymous_id	string	Yes	Anonymous user ID to link
user_id	string	Yes	Identified user ID
traits	object	No	User properties

Response

Status: 200 OK

{
  "success": true
}

---

Tag Enrichment

Events are automatically enriched with these tags:

Tag	Description
__browser	Browser name
__browser_version	Browser version
__os	Operating system
__os_version	OS version
__device	Device type
__country	Country code
__region	Region/State
__city	City
__session_id	Session ID
__path	Page path
__referrer	Referrer URL
__utm_source	UTM source
__utm_medium	UTM medium
__utm_campaign	UTM campaign

---

HTTP Status Codes

Code	Description
200	Success
202	Accepted (queued)
400	Invalid parameters
401	Invalid SDK key
404	Not found
429	Rate limited
503	Service unavailable

Rate Limits

• Standard: 1,000 requests per minute
• Burst: 100 requests per second

When rate limited, retry after the Retry-After header value.