REST API

The Altertable Product Analytics API provides direct HTTP access to track events and identify users. For most use cases, we recommend using the JavaScript or React SDKs, which provide a simpler interface and handle session management automatically.

Successful responses from both endpoints return the same JSON shape: ok, task_id, and error_code.

Connection details

Authentication

All API requests require a public Product Analytics API key.

See the Authentication guide for details on obtaining and managing API keys.

POST /track

Track one event or a batch of events.

Query Parameters:

• sync (optional): When sync=true, the API waits for the task to complete before returning.

POST https://api.altertable.ai/track?sync=true
Copy

Request:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
curl -X POST https://api.altertable.ai/track \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment":"production",
    "event": "Purchase Completed",
    "properties": {
      "product_id": "p_01jza8fr5efvgbxxdd1bwkd0m5",
      "amount": 99.99,
      "currency": "USD"
    },
    "distinct_id": "u_01jza857w4f23s1hf2s61befmw"
  }'

Request Body:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
{
  "environment": "production",
  "event": "Button Clicked",
  "properties": {
    "button_name": "Sign Up",
    "location": "header"
  },
  "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
  "device_id": "device-0197d9df-3c3b-734e-96dd-dfda52b0167c",
  "session_id": "sess_0197d9df-3c3b-734e-96dd-dfda52b0167c",
  "timestamp": "2025-01-15T10:30:00Z"
}

Request Parameters:

Response:

Returns 200 OK with a JSON body:

Copy
1
2
3
4
5
{
  "ok": true,
  "task_id": "019d68d4-c4cb-7e40-ad50-fd4b68c2045e",
  "error_code": null
}

• ok: whether the request was accepted
• task_id: task identifier you can use to track asynchronous processing
• error_code: endpoint-specific error code when the request was not successful

Error codes:

• environment-not-found
• invalid-headers
• unknown-built-in-property

POST /identify

Create or update one identity or a batch of identities.

Query Parameters:

• sync (optional): When sync=true, the API waits for the task to complete before returning.

POST https://api.altertable.ai/identify?sync=true
Copy

Request:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
curl -X POST https://api.altertable.ai/identify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment":"production",
    "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
    "traits": {
      "email": "[email protected]",
      "name": "John Doe",
      "company": "Acme Corp",
      "plan": "premium"
    }
  }'

Request Body:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
{
  "environment": "production",
  "distinct_id": "u_01jza857w4f23s1hf2s61befmw",
  "anonymous_id": "visitor-0197d9df-3c3b-734e-96dd-dfda52b0167c",
  "traits": {
    "email": "[email protected]",
    "name": "John Doe",
    "plan": "premium",
    "signup_date": "2025-01-01"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

Request Parameters:

Response:

Returns 200 OK with a JSON body:

Copy
1
2
3
4
5
{
  "ok": true,
  "task_id": "019d68d4-c4cb-7e40-ad50-fd5bd4956505",
  "error_code": null
}

• ok: whether the request was accepted
• task_id: task identifier you can use to track asynchronous processing
• error_code: endpoint-specific error code when the request was not successful

Error codes:

• environment-not-found

Best practices

• Use SDKs when possible: The SDKs handle retries, queuing, and session management automatically
• Identify users for better tracking: Use POST /identify to set user context, then include distinct_id in subsequent track requests to associate events with users
• Batch payloads when needed: Both endpoints accept either a single payload or an array
• Use consistent event names: Use clear, consistent naming conventions for events
• Validate data: Ensure event properties and user traits are valid JSON
• Send the environment explicitly: Both endpoints require an environment field in the request body

Next steps

• Use SDKs: Simplify integration with JavaScript or React SDKs
• Track Events: Learn more about event tracking
• Identify Users: Learn more about user identification