API Reference
Upsurge exposes versioned REST endpoints for storefront runtimes and authenticated merchant operations. Use the browser SDK for ordinary storefront capture; call the HTTP API directly for server, native, or custom runtime integrations.
Base URL
https://dashboard.upsur.ge/api/v1
The /api/v1 path is the current HTTP contract. Documentation versions preserve guidance when a breaking platform contract requires a frozen snapshot.
Choose the authentication model
| Integration | Credential | Typical endpoints |
|---|---|---|
| Storefront tracking | Public site ID exchanged for a short-lived runtime token | Events, recommendations, public overlay/chatbot configuration, submissions |
| Trusted server backend | Scoped secret API key | Server events, profile imports, authoritative commerce, and partner conversions |
| Merchant dashboard or trusted merchant client | Firebase ID token | Sites, API keys, products, campaigns, workflows, analytics, integrations, media |
| Platform worker or webhook sender | Dedicated secret/signature | Internal job processing and workflow webhook delivery; not a site-key API |
Read Authentication before calling an endpoint directly.
Quick start: track one event
curl --request POST \
'https://dashboard.upsur.ge/api/v1/events/track' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: upsurge_sk_test_replace_me' \
--data '{
"event_type": "product_view",
"session_id": "session_01JEXAMPLE",
"device_id": "device_01JEXAMPLE",
"properties": {
"product_id": "SKU-TRAIL-123",
"product_name": "Trail Runner",
"product_price": 129.0,
"currency": "USD"
},
"context": {
"page_url": "https://shop.example.com/products/trail-runner",
"user_agent": "custom-storefront/1.0"
}
}'
A new event returns 201, an event_id, a timestamp, and request metadata. See Event ingestion for batching and schemas.
Reference sections
/api/admin/*, integration job processors, and platform-signed callbacks are operational surfaces, not customer site-key APIs. Do not call them from storefront code or expose their credentials in a browser.