Build with AI agents

Everything an AI agent, such as Claude, ChatGPT, Codex or Cursor, needs to add Specvista Analytics to a codebase or read its reports.

Entry points

How an agent gets access

• To send events, the agent needs a project key. The person copies it from the Properties page of the dashboard and stores it as SA_API_KEY, or the agent reads it with GET /api/v1/projects using their token.
• To read reports, the agent needs a bearer token in SA_TOKEN. The person runs the sign-in command in Get a project key themselves. The token lasts 90 days and gives full access to that account, including keys, so keep it out of logs and commits.
• Never ask for, type or store the person's password, and never create an account or property without the person's go-ahead.

Try things safely

There is no sandbox or test mode yet. Instead:

• Read-only checks need no account: GET /api/v1/sdk.js, GET /api/v1/openapi.json and GET /api/v1/ingest/ignore-status.
• Every call to POST /ingest stores a real event. Send test events to a separate property, for example one named "Test", rather than to a live one.
• Events sent with "environment":"development" are stored as internal and left out of every report, so they cannot skew numbers. They also do not appear in reports, so use a test property when you need to see the result.
• Reports are read-only and safe to call.
• Ask first before anything that cannot be undone: POST /forget, the account.deleted event, DELETE /projects/{id} and POST /projects/{id}/rotate-key.

Rules for your repository

Paste this into AGENTS.md, CLAUDE.md or your editor's rules file:

## Analytics: Specvista Analytics

- Docs: https://analytics.specvista.com/llms.txt (Markdown pages: add .md to any docs URL).
- API base: https://analyticsapi.specvista.com/api/v1. Contract: /openapi.json.
- Websites: one script tag, https://analyticsapi.specvista.com/api/v1/sdk.js with data-api-key.
  Custom events: window.saTrack(name, props); they send only after the visitor accepts analytics.
- Servers: POST /ingest with X-Api-Key from the SA_API_KEY environment variable and "source":"backend".
- Check npm view specvista-analytics-node version (or -rn) before installing; if 404, use HTTP.
- Event names: lower case object.action, for example checkout.completed. Never put secrets,
  passwords, payment details or free text in properties.
- Never commit keys or tokens. Never call /forget, rotate a key or delete a property without asking.
- Errors carry a code and a doc_url; follow the doc_url.

Main tasks

• Get a project key
• Add tracking to a website
• Add tracking to a Node.js server
• Add tracking to a React Native app
• Read reports
• Errors