# webanalytics.sh

> First-party web analytics. This file explains how scripts and AI agents can manage websites in a customer's workspace through the HTTP API at https://webanalytics.sh.

## Authentication

Authenticate with your workspace access token (it starts with wsa_) as a Bearer token. It has full access to your workspace: keep it in a secret store, never in page HTML or a repository. Regenerating the token in the dashboard immediately revokes the old one.

Send: Authorization: Bearer <workspace token>

## Create a website

curl -X POST https://webanalytics.sh/api/sites \
  -H "Authorization: Bearer $WEBANALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Tandlæge Hillerød","origins":["tandlægehillerød.dk"]}'

Response (201):

{
  "site": { "id": "3f2c…", "name": "Tandlæge Hillerød", "origins": ["https://xn--tandlgehillerd-4ib01a.dk"], … },
  "snippet": "<script defer src=\"/_analytics/script.js\" data-site=\"3f2c…\"></script>"
}

## Endpoints

- POST /api/sites: Create a website. Body: name, origins (1–10 addresses), optional goals and property_keys.
- GET /api/sites: List the websites in your workspace.
- GET /api/portfolio: Human pageviews per website for the last 14 complete UTC days (provisional): current is the last 7 days, previous the 7 before.
- GET /api/sites/{id}: Read one website’s configuration.
- PUT /api/sites/{id}: Update name, origins, goals, property_keys and enabled.
- GET /api/sites/{id}/report?start=YYYY-MM-DD&end=YYYY-MM-DD&filter=human: Historical report; returns a queued job until it is ready.

## Rules

- Origins can be bare domains (example.com), full URLs or internationalized names (tandlægehillerød.dk). They are stored as HTTPS origins in ASCII form; paths are ignored.
- Creating websites requires an active subscription (otherwise 402) and allows up to five websites per workspace (otherwise 409 website_limit_reached).
- Errors are JSON: {"error": "code", "message": "explanation"}. Date ranges are UTC, start-inclusive and end-exclusive.

## More

- Pricing: https://webanalytics.sh/pricing/
- Human-readable version of this file: https://webanalytics.sh/developers/