REST API Reference & Overview
The Keystone CDP REST API allows developers to query customer profiles, manage audiences, ingest events, trigger activations, and configure workspace schemas programmatically.
1. Base URL & Protocol
All API requests must be transmitted over encrypted HTTPS:
Production Base URL: https://cdp.your-domain.com/api
For live interactive endpoint exploration and schema inspection, visit the Interactive API Explorer.
2. Authentication & Headers
Authenticate API requests by supplying your secret workspace API Key in the X-API-Key request header:
GET /tenant/profiles HTTP/1.1
Host: cdp.your-domain.com
X-API-Key: kst_live_9f8e7d6c5b4a3...
Content-Type: application/json
Keep your secret API keys confidential. Never commit keys to public GitHub repositories or expose them in client-side mobile applications. Use Public Tracking Keys for client-side web scripts.
3. Standard Response Format
Keystone returns JSON responses adhering to REST standards:
Success Response (200 OK):
{
"status": "success",
"data": {
"id": "c1f78e22-3a9d-4e0a-9d21-f0987b654321",
"email": "[email protected]",
"first_name": "Sarah",
"last_name": "Connor",
"total_spend": 2840.50,
"rfm_segment": "Champions",
"churn_risk_score": 0.12,
"predicted_clv": 4500.00,
"created_at": "2025-11-14T10:22:30Z"
}
}
Error Response (400 Bad Request / 401 Unauthorized / 404 Not Found):
{
"status": "error",
"error_code": "INVALID_TENANT_KEY",
"message": "The provided API key does not have access to this tenant workspace.",
"timestamp": "2026-10-12T13:45:00Z"
}
4. Primary API Resource Groups
| Category | Endpoints | Description |
|---|---|---|
| Profiles & Customers | GET /tenant/profilesGET /tenant/profiles/{id}POST /tenant/profiles |
Query unified customer 360 records, retrieve traits, and update customer metadata. |
| Identity Resolution | POST /identity/mergeGET /identity/graph/{id} |
Inspect connected identity nodes and trigger programmatic profile merges. |
| Audiences & Segments | GET /tenant/segmentsPOST /tenant/segments/calculate |
Fetch active cohort memberships and evaluate dynamic queries. |
| Orders & Commerce | GET /tenant/ordersGET /tenant/products |
Manage orders, line items, and product catalog inventory. |
| Ingestion | POST /api/ingestPOST /tenant/ingest/batch |
Stream real-time events and submit asynchronous batch loads. |
| Predictive AI | GET /intelligence/clv/{id}GET /intelligence/churn/{id} |
Retrieve machine learning predictions and recommendations. |
5. Rate Limits & Pagination
Rate Limits:
- Standard Tier: 1,000 requests per minute per tenant API key.
- Batch Ingest Tier: Up to 10,000 events per minute with burst buffering in Redis.
- Rate-limited responses return
429 Too Many Requestswith aRetry-After: <seconds>header.
Pagination:
Collection endpoints utilize cursor-based pagination for high performance:
GET /tenant/profiles?limit=50&cursor=eyJpZCI6ImMzZDQ..."
Response pagination metadata includes:
{
"pagination": {
"limit": 50,
"next_cursor": "eyJpZCI6ImM0ZTV...",
"has_more": true
}
}