OpenPanel REST API with cURL

This guide demonstrates how to interact with the OpenPanel API using cURL. These examples provide a low-level understanding of the API endpoints and can be useful for testing or for integrations where a full SDK isn't available.

Good to know

If you want to track geo location you'll need to pass the ip property as a header x-client-ip
If you want to track device information you'll need to pass the user-agent property as a header user-agent

Authentication

All requests to the OpenPanel API require authentication. You'll need to include your clientId and clientSecret in the headers of each request.

-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET"

Usage

Base URL

All API requests should be made to:

https://api.openpanel.dev

Tracking Events

To track an event:

curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "track",
  "payload": {
    "name": "my_event",
    "properties": {
      "foo": "bar"
    }
  }
}'

Identifying Users

To identify a user:

curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "identify",
  "payload": {
    "profileId": "123",
    "firstName": "Joe",
    "lastName": "Doe",
    "email": "[email protected]",
    "properties": {
      "tier": "premium"
    }
  }
}'

Creating Aliases

To create an alias for a user:

curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "alias",
  "payload": {
    "profileId": "1",
    "alias": "a1"
  }
}'

Incrementing Properties

To increment a numeric property:

curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "increment",
  "payload": {
    "profileId": "1",
    "property": "visits",
    "value": 1
  }
}'

Decrementing Properties

To decrement a numeric property:

curl -X POST https://api.openpanel.dev/track \
-H "Content-Type: application/json" \
-H "openpanel-client-id: YOUR_CLIENT_ID" \
-H "openpanel-client-secret: YOUR_CLIENT_SECRET" \
-d '{
  "type": "decrement",
  "payload": {
    "profileId": "1",
    "property": "visits",
    "value": 1
  }
}'

Error Handling

The API uses standard HTTP response codes to indicate the success or failure of requests. In case of an error, the response body will contain more information about the error. Example error response:

{
  "error": "Invalid client credentials",
  "status": 401
}

Rate Limiting

The API implements rate limiting to prevent abuse. If you exceed the rate limit, you'll receive a 429 (Too Many Requests) response. The response will include headers indicating your rate limit status.

Best Practices

Always use HTTPS to ensure secure communication.
Store your clientId and clientSecret securely and never expose them in client-side code.
Implement proper error handling in your applications.
Respect rate limits and implement exponential backoff for retries.

JavaScript Export