API Reference

The Clayva API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

The Clayva API uses API keys to authenticate requests. You can view and manage your API keys in the Clayva Dashboard. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Bearer Auth. Provide your API key as the bearer token:

Authorization: Bearer YOUR_API_KEY

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Events API

Events are the core of Clayva's analytics. Use these endpoints to track user actions, system events, and any custom events in your application.

Track Event

Example Request

curl -X POST https://api.clayva.com/v1/events/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Product Viewed",
    "userId": "user_123",
    "properties": {
      "productId": "SKU-456",
      "productName": "Wireless Mouse",
      "price": 29.99
    }
  }'

const response = await fetch('https://api.clayva.com/v1/events/track', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event: 'Product Viewed',
    userId: 'user_123',
    properties: {
      productId: 'SKU-456',
      productName: 'Wireless Mouse',
      price: 29.99
    }
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.clayva.com/v1/events/track',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'event': 'Product Viewed',
        'userId': 'user_123',
        'properties': {
            'productId': 'SKU-456',
            'productName': 'Wireless Mouse',
            'price': 29.99
        }
    }
)

data = response.json()

Success Response

{
  "success": true,
  "data": {
    "eventId": "evt_2KtY3kPl9vR8mNxZ",
    "event": "Product Viewed",
    "userId": "user_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "properties": {
      "productId": "SKU-456",
      "productName": "Wireless Mouse",
      "price": 29.99
    },
    "context": {
      "library": {
        "name": "clayva-js",
        "version": "1.2.0"
      }
    }
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_EVENT_NAME",
    "message": "Event name cannot be empty or null",
    "details": {
      "field": "event",
      "provided": null
    }
  }
}

Batch Events

The batch endpoint accepts an array of events, each following the same structure as the single event endpoint. Maximum 1000 events per batch.

{
  "events": [
    {
      "event": "Product Viewed",
      "userId": "user_123",
      "properties": { ... }
    },
    {
      "event": "Add to Cart",
      "userId": "user_123",
      "properties": { ... }
    }
  ]
}

Get Event

Users API

Manage user profiles and properties. These endpoints allow you to identify users, update their attributes, and retrieve user information.

Identify User

Get User

Update User

Workspaces API

Manage workspaces and their settings. Workspaces allow you to organize your analytics data and control access for your team.

Rate Limits

The Clayva API implements rate limiting to ensure fair usage and maintain service reliability. Rate limits are enforced per API key.

Error Handling

Clayva uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with Clayva's servers.