> ## Documentation Index
> Fetch the complete documentation index at: https://canopy.wnstn.space/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cano Analytics REST API: Reference and Quick Start

> Explore the Cano Analytics REST API to track events, manage users, query dashboards, and automate workflows from any backend or script.

The Cano Analytics REST API gives you programmatic access to everything the platform can do — track events, identify users, query dashboard data, and automate workspace workflows. Any HTTP client can integrate with it, and all endpoints share the same conventions so you can move quickly from your first request to a production-grade integration.

## Base URL

All API requests are made to the following base URL:

```
https://api.canoanalytics.io/v1
```

## API Conventions

Before making your first request, familiarize yourself with the conventions used across every endpoint.

**Requests and responses**
All request bodies must be sent as JSON, and all responses are returned as JSON. Include the `Content-Type: application/json` header on every request that sends a body.

**Timestamps**
All timestamps are formatted as [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) strings in UTC (e.g., `2024-11-01T14:32:00Z`).

**Resource IDs**
Every resource has a prefixed string ID that indicates its type at a glance:

| Prefix  | Resource   |
| ------- | ---------- |
| `evt_`  | Events     |
| `usr_`  | Users      |
| `dash_` | Dashboards |
| `rpt_`  | Reports    |

**Errors**
Failed requests return a JSON body with a top-level `error` object containing a machine-readable `code` and a human-readable `message`. Use `error.code` in your error-handling logic and `error.message` for logging.

## Quick Example

The following request tracks a `page_viewed` event for a user. Swap in your own API key, user ID, and properties to run it immediately.

```bash theme={null}
curl -X POST https://api.canoanalytics.io/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "page_viewed", "user_id": "usr_123", "properties": { "page": "/pricing" } }'
```

## Response Format

Every API response follows one of two shapes depending on whether the request succeeded or failed.

<Tabs>
  <Tab title="Success">
    A successful response returns a `2xx` status code and a JSON body describing the created or queried resource.

    ```json Success Response theme={null}
    {
      "id": "evt_abc123",
      "status": "queued"
    }
    ```
  </Tab>

  <Tab title="Error">
    A failed response returns a `4xx` or `5xx` status code and a JSON body with an `error` object.

    ```json Error Response theme={null}
    {
      "error": {
        "code": "unauthorized",
        "message": "Invalid API key"
      }
    }
    ```
  </Tab>
</Tabs>

## Next Steps

Before making API calls, set up authentication and review the rate limits so your integration stays healthy.

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/api-reference/authentication">
    Learn how to generate API keys and attach them to every request.
  </Card>

  <Card title="Rate Limits" icon="gauge-high" href="/docs/api-reference/rate-limits">
    Understand per-endpoint quotas and how to handle 429 responses gracefully.
  </Card>
</CardGroup>

## Explore the API

<CardGroup cols={2}>
  <Card title="Events" icon="bolt" href="/docs/api-reference/events">
    Track user actions and custom events from any source.
  </Card>

  <Card title="Users" icon="user" href="/docs/api-reference/users">
    Identify users and enrich their profiles with traits.
  </Card>

  <Card title="Dashboards" icon="chart-line" href="/docs/api-reference/dashboards">
    Query and manage your analytics dashboards programmatically.
  </Card>

  <Card title="Reports" icon="file-chart-column" href="/docs/api-reference/reports">
    Generate and export reports from your workspace data.
  </Card>
</CardGroup>