Agent Analytics API API

openapi: 3.1.0
info:
  title: Agent Analytics API
  version: 1.0.0
  description: |
    Web analytics platform with an HTTP API that AI agents can query.

    **Docs:** [Home](https://docs.agentanalytics.sh) · [Getting Started](https://docs.agentanalytics.sh/getting-started/) · [Installation](https://docs.agentanalytics.sh/installation/) · [API Reference](https://docs.agentanalytics.sh/api/) · [OpenAPI Spec](https://docs.agentanalytics.sh/openapi.yaml)

    **Quick start:**

    1. Start an agent session with `POST /agent-sessions/start` or sign in on the dashboard.
    2. Create a project with `POST /projects`.
    3. Add the returned tracker snippet to your site.
    4. Query analytics with `GET /stats`.

    **Authentication:**

    - `aas_*` agent sessions are the primary machine-auth mechanism for CLI, MCP, and managed runtimes.
    - `aak_*` API keys are an advanced/manual fallback for direct HTTP users.
    - `aat_*` project tokens are public and used for ingestion only.

    Installation guides for Claude Code, Claude Desktop / Cowork, Cursor, and OpenAI Codex now live in the docs site instead of this OpenAPI intro block.

  contact:
    email: support@agentanalytics.sh
    url: https://agentanalytics.sh
  license:
    name: MIT
    url: https://github.com/Agent-Analytics/agent-analytics/blob/main/LICENSE

servers:
  - url: https://api.agentanalytics.sh
    description: Production (hosted)

tags:
  - name: Ingestion
    description: Event tracking endpoints called by the browser `tracker.js` script. These use a public project token (`aat_*`) — not your API key. You don't call these directly; the tracker handles it.
  - name: Analytics
    description: Query analytics data. Requires account auth. Agent-session bearer auth is preferred; API keys remain a supported fallback.
  - name: Session Replay
    description: Explicitly opt in projects, list linked replay metadata, create short-lived viewer links, inspect usage, and delete retained recordings. Pro or complimentary access only.
  - name: Projects
    description: Manage projects programmatically. Requires account auth. Agent-session bearer auth is preferred; API keys remain a supported fallback.
  - name: Project Context
    description: Store compact goals, activation events, event-name glossary entries, and date annotations so agents can interpret analytics results with project-specific meaning.
  - name: Website Analysis
    description: Product Growth Scanner. Anonymous previews return growth questions, measurement blind spots, and first instrumentation decisions; full analysis and project linking require account auth.
  - name: Account
    description: Account information and feedback. Agent-session bearer auth is preferred for scoped account reads and feedback; raw API-key management is dashboard-only or API-key fallback only.
  - name: Agent Sessions
    description: Agent-session signup/login, detached approval, refresh, revocation, and account-side session management.
  - name: Experiments
    description: |
      A/B testing experiments. Create experiments, assign variants client-side via tracker.js, and query results with Bayesian significance. Pro tier only.

      ## Declarative Experiments (recommended)

      The simplest way to run experiments — no custom JavaScript needed. Mark elements with HTML attributes and tracker.js handles variant assignment automatically.

      ### Anti-Flicker Snippet

      Add this in `<head>` **before** the tracker.js script tag to prevent flash of control content:

      ```html
      <style>.aa-loading [data-aa-experiment]{visibility:hidden!important}</style>
      <script>document.documentElement.classList.add('aa-loading');
      setTimeout(function(){document.documentElement.classList.remove('aa-loading')},3000)</script>
      ```

      - Uses `visibility: hidden` to preserve layout (not `display: none`)
      - Only hides `[data-aa-experiment]` elements, not the entire page
      - 3-second timeout fallback shows control content if config fetch fails
      - tracker.js removes the `aa-loading` class after applying variants

      ### Declarative Attributes

      ```html
      <h1 data-aa-experiment="hero_text"
          data-aa-variant-b="Try it free today!">
        Start your free trial
      </h1>
      ```

      - Original element content = control variant
      - `data-aa-variant-{key}` attributes provide replacement text for non-control variants
      - Multiple elements can share the same experiment name (same variant assigned to all)
      - Variant keys are lowercased for attribute lookup
      - Requires a server-side experiment config (created via `POST /experiments`)

      ### Programmatic API

      For complex cases that can't be expressed as text swaps:

      ```js
      var variant = window.aa?.experiment('signup_cta', ['control', 'new_cta']);
      if (variant === 'new_cta') {
        document.querySelector('.cta').style.backgroundColor = 'green';
      }
      ```

      ### URL Param Variant Forcing

      Force a specific variant via URL parameter — useful for ad landing pages, QA testing, or sharing a specific variant with teammates.

      ```
      https://yoursite.com/pricing/?aa_variant_signup_cta=new_cta
      ```

      Format: `?aa_variant_<experiment_name>=<variant_key>`

      - The forced variant must exist in the experiment config — invalid values fall through to normal hash assignment
      - Works with both declarative and programmatic experiments
      - Exposure events include `forced: true` so you can filter them in analytics
      - No URL param = existing hash-based assignment (backward compatible)
  - name: Funnels
    description: |
      Ad-hoc funnel analysis — track where users drop off across a sequence of events.
      No saved funnels — agents query in one shot via `POST /funnel`.
  - name: Paths
    description: |
      Bounded session path analysis from entry pages to goal, drop-off, or truncation.
      Built for agent workflows: pages → funnels → retention → experiments.
  - name: Streaming
    description: |
      Real-time event streaming.

      `/stream` and `/live` are Pro-only on hosted cloud. Both read from an in-memory ring buffer — no D1 query.


# --- truncated at 32 KB (192 KB total) ---
# Full source: https://artifacts.apis.io/agentanalytics-sh/openapi/_original/agentanalytics-sh-api-openapi.yml