Cano Analytics REST API Integration and Usage Guide

If there’s no official SDK for your language or runtime, you can integrate with Cano Analytics directly over HTTP — the REST API is straightforward, follows standard conventions, and works from any environment that can make an HTTPS request. This guide walks you through authentication, tracking events, identifying users, batching, and handling errors.

Base URL and Authentication

All API requests go to the following base URL. Every request must include an Authorization header with your API key as a Bearer token and a Content-Type of application/json.

Base URL:      https://api.canoanalytics.io/v1
Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

You can find your API key in the Cano dashboard under Settings → API Keys.

Keep your API key secret. Never expose it in client-side JavaScript, public repositories, or logs. Use environment variables or a secrets manager to inject it at runtime.

Track an Event

Send a POST request to /events with an event name, a user identifier, and any properties you want to capture.

track-event.sh

curl -X POST https://api.canoanalytics.io/v1/events \
  -H "Authorization: Bearer cano_live_sk_1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "page_viewed",
    "user_id": "usr_123",
    "properties": {
      "page": "/pricing",
      "referrer": "https://google.com"
    }
  }'

Expected response (201 Created):

{
  "status": "queued",
  "event_id": "evt_01hx9zk2b3c4d5e6f7g8h9j0"
}

The same request in other languages:

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	payload := map[string]any{
		"event":   "page_viewed",
		"user_id": "usr_123",
		"properties": map[string]string{
			"page":     "/pricing",
			"referrer": "https://google.com",
		},
	}

	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", "https://api.canoanalytics.io/v1/events", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "Bearer cano_live_sk_1234567890")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	fmt.Println("Status:", resp.Status)
}

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://api.canoanalytics.io/v1/events')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer cano_live_sk_1234567890'
request['Content-Type']   = 'application/json'
request.body = {
  event:      'page_viewed',
  user_id:    'usr_123',
  properties: {
    page:     '/pricing',
    referrer: 'https://google.com'
  }
}.to_json

response = http.request(request)
puts "Status: #{response.code}"
puts response.body

<?php

$payload = json_encode([
    'event'      => 'page_viewed',
    'user_id'    => 'usr_123',
    'properties' => [
        'page'     => '/pricing',
        'referrer' => 'https://google.com',
    ],
]);

$ch = curl_init('https://api.canoanalytics.io/v1/events');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer cano_live_sk_1234567890',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "Status: $status\n";
echo $response . "\n";

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class TrackEvent {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "event": "page_viewed",
              "user_id": "usr_123",
              "properties": {
                "page": "/pricing",
                "referrer": "https://google.com"
              }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.canoanalytics.io/v1/events"))
            .header("Authorization", "Bearer cano_live_sk_1234567890")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println("Status: " + response.statusCode());
        System.out.println(response.body());
    }
}

Identify a User

Send a POST to /identify to associate a user ID with a set of traits. Call this after a user signs up or logs in so that all future events from that ID are enriched with their profile data.

identify-user.sh

curl -X POST https://api.canoanalytics.io/v1/identify \
  -H "Authorization: Bearer cano_live_sk_1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_123",
    "traits": {
      "name": "Ada Lovelace",
      "email": "[email protected]",
      "plan": "pro",
      "created_at": "2024-01-15T09:00:00Z"
    }
  }'

Expected response (200 OK):

{
  "status": "ok",
  "user_id": "usr_123"
}

Batch Events

To reduce HTTP round-trips, send multiple events in a single request by posting an array to /events/batch. You can include up to 500 events per batch.

batch-events.sh

curl -X POST https://api.canoanalytics.io/v1/events/batch \
  -H "Authorization: Bearer cano_live_sk_1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event": "page_viewed",
        "user_id": "usr_123",
        "properties": { "page": "/dashboard" }
      },
      {
        "event": "button_clicked",
        "user_id": "usr_123",
        "properties": { "button": "export_csv" }
      },
      {
        "event": "export_completed",
        "user_id": "usr_123",
        "properties": { "format": "csv", "rows": 1420 }
      }
    ]
  }'

Expected response (200 OK):

{
  "status": "queued",
  "accepted": 3,
  "rejected": 0
}

Pagination

Endpoints that return lists of records (such as GET /events) use cursor-based pagination. Each response includes a next_cursor field — pass its value as the cursor query parameter to fetch the next page. When next_cursor is null, you have reached the last page.

pagination.sh

# First page — returns up to 100 events
curl 'https://api.canoanalytics.io/v1/events?limit=100' \
  -H 'Authorization: Bearer cano_live_sk_1234567890'

# Next page — pass the cursor from the previous response
curl 'https://api.canoanalytics.io/v1/events?limit=100&cursor=eyJpZCI6ImV2dF8xMjMifQ==' \
  -H 'Authorization: Bearer cano_live_sk_1234567890'

A paginated response looks like this:

{
  "data": [ /* array of event objects */ ],
  "next_cursor": "eyJpZCI6ImV2dF80NTYifQ==",
  "has_more": true
}

Cursors are opaque, base64-encoded strings. Do not attempt to decode or construct them manually — always use the next_cursor value returned by the previous response.

Error Handling

The API returns standard HTTP status codes. All error responses include a JSON body with a machine-readable error_code and a human-readable message.

{
  "error_code": "invalid_api_key",
  "message": "The API key provided is invalid or has been revoked.",
  "docs_url": "https://docs.canoanalytics.io/errors/invalid_api_key"
}

Status	Error Code	Meaning	How to Handle
`400`	`bad_request`	Malformed JSON or missing required field	Fix the request payload before retrying
`401`	`invalid_api_key`	API key is missing, invalid, or revoked	Verify your key in the dashboard; do not retry automatically
`403`	`forbidden`	Valid key but insufficient permissions for this operation	Check your key’s scope in the dashboard
`404`	`not_found`	Resource does not exist	Verify the resource ID; do not retry
`422`	`validation_error`	Payload is well-formed but fails validation (e.g. unknown field)	Inspect the `details` array in the response body for field-level errors
`429`	`rate_limited`	Too many requests — rate limit exceeded	Respect the `Retry-After` header and implement exponential backoff
`500`	`server_error`	Unexpected error on Cano’s side	Retry with exponential backoff; check status.canoanalytics.io

For 429 responses, the API includes a Retry-After header with the number of seconds to wait before retrying:

HTTP/2 429
Retry-After: 15
Content-Type: application/json

{
  "error_code": "rate_limited",
  "message": "Rate limit exceeded. Try again in 15 seconds."
}

If an official SDK exists for your language, use it instead of calling the REST API directly. The JavaScript SDK and Python SDK handle batching, automatic retries, exponential backoff, and persistent queuing out of the box — saving you from re-implementing that logic yourself.

Overview

Endpoints

SDKs

Cano Analytics REST API Integration and Usage Guide

Base URL and Authentication

Track an Event

Identify a User

Batch Events

Error Handling

​Base URL and Authentication

​Track an Event

​Identify a User

​Batch Events

​Pagination

​Error Handling

Base URL and Authentication

Track an Event

Identify a User

Batch Events

Pagination

Error Handling