# API Overview

> Access your analytics data programmatically with Databuddy's REST API


import { Card, Cards, Callout, CodeBlock } from "@/components/docs";

Access your analytics data programmatically with Databuddy's REST API. Most endpoints require authentication and are rate-limited for security. Public exceptions: `/health`, `GET /v1/query/types`, the public feature-flag routes under `/public/v1/flags/*`, and the `/.well-known/*` discovery routes.

<Callout type="info">
  **Try it live!** Test all these endpoints interactively in our [API Playground](https://api.databuddy.cc/) with real data and see instant responses.
</Callout>

## Base URLs

| Service | URL | Purpose |
|---------|-----|---------|
| Analytics API | `https://api.databuddy.cc/v1` | Query analytics data |
| Event Tracking | `https://basket.databuddy.cc` | Send custom events |
| OpenAPI spec | `https://www.databuddy.cc/openapi.json` | Machine-readable Databuddy REST API schema |
| API reference | `https://api.databuddy.cc/` | Interactive Databuddy API reference |
| MCP server | `https://api.databuddy.cc/v1/mcp` | Streamable HTTP MCP endpoint for AI agents |
| MCP manifest | `https://www.databuddy.cc/.well-known/mcp.json` | Machine-readable MCP discovery manifest |

## Quick Start

**1. Get your API key** from [Dashboard → Organization Settings → API Keys](https://app.databuddy.cc/organizations/settings#api-keys)

**2. List your websites:**

<CodeBlock 
  language="bash"
  code={`curl -H "x-api-key: dbdy_your_api_key" \\
  https://api.databuddy.cc/v1/query/websites`}
/>

**3. Query analytics data:**

<CodeBlock 
  language="bash"
  code={`curl -X POST -H "x-api-key: dbdy_your_api_key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "parameters": ["summary_metrics", "top_pages"],
    "preset": "last_30d"
  }' \\
  "https://api.databuddy.cc/v1/query?website_id=web_123"`}
/>

Use date presets like `last_7d`, `last_30d`, `this_month` instead of explicit dates for convenience.

## API Sections

<Cards>
  <Card title="Authentication" href="/docs/api/authentication">
    API keys, scopes, and authentication methods
  </Card>
  <Card title="Analytics Queries" href="/docs/api/query">
    Query website analytics with flexible parameters
  </Card>
  <Card title="Event Tracking" href="/docs/api/events">
    Send custom events programmatically
  </Card>
  <Card title="Link Analytics" href="/docs/api/links">
    Query link shortener click data
  </Card>
  <Card title="Error Handling" href="/docs/api/errors">
    Error codes and troubleshooting
  </Card>
  <Card title="Rate Limits" href="/docs/api/rate-limits">
    Rate limiting by plan and endpoint
  </Card>
</Cards>

## Available Query Types

### Website Analytics

Query types for `website_id`:

| Type | Description |
|------|-------------|
| `summary_metrics` | Overall website metrics and KPIs |
| `top_pages` | Page views and visitors by path |
| `traffic_sources` | Traffic source breakdown |
| `top_referrers` | Top referrers |
| `browser_name` | Browser usage breakdown |
| `os_name` | Operating system breakdown |
| `device_types` | Device category (mobile/desktop/tablet) |
| `country` | Visitors by country |
| `city` | Visitors by city |
| `recent_errors` | Latest JavaScript errors |
| `error_summary` | Error counts and impact |
| `vitals_overview` | Core Web Vitals overview |
| `page_performance` | Page views and visitors by page; for load timing use `vitals_by_page` |
| `session_metrics` | Session metrics over time |
| `session_list` | Individual sessions |
| `custom_events` | Custom event data |
| `profile_list` | User profile analytics |
| `outbound_links` | External link clicks |
| `outbound_domains` | External clicks by domain |
| `scroll_depth_summary` | Scroll depth engagement |
| `interaction_summary` | Interaction engagement |
| `frustration_by_page` | Rage clicks, dead clicks, and errors per page |
| `form_abandonment_by_page` | Form starts, submits, and the field visitors stop on |
| `engagement_quality_by_page` | Active time, attention ratio, and interaction per page |

This is a subset. Use `GET /v1/query/types` for the full list.

### Link Shortener Analytics

Query types for `link_id`:

| Type | Description |
|------|-------------|
| `link_total_clicks` | Total click count |
| `link_clicks_by_day` | Daily click breakdown |
| `link_referrers_by_day` | Daily clicks by referrer |
| `link_countries_by_day` | Daily clicks by country |
| `link_top_referrers` | Top traffic sources |
| `link_top_countries` | Top countries |
| `link_top_regions` | Top regions |
| `link_top_cities` | Top cities |
| `link_top_devices` | Device breakdown |
| `link_top_browsers` | Browser breakdown |

## Health Check

Check API availability:

<CodeBlock 
  language="http"
  code="GET /health"
/>

<CodeBlock 
  language="json"
  code={`{
  "status": "ok"
}`}
/>