# 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

| Entry point | Address | Status |
|---|---|---|
| `llms.txt` | `https://analytics.specvista.com/llms.txt` | Live |
| `llms-full.txt`, every page in one file | `https://analytics.specvista.com/llms-full.txt` | Live |
| Markdown for any docs page | Add `.md` to the page address, for example `https://analytics.specvista.com/docs/track-web.md` | Live |
| OpenAPI | `https://analyticsapi.specvista.com/api/v1/openapi.json` | Live |
| HTTP API | `https://analyticsapi.specvista.com/api/v1` | Live |
| Browser script | `https://analyticsapi.specvista.com/api/v1/sdk.js` | Live |
| Node.js SDK | `specvista-analytics-node` | Not yet on npm |
| React Native SDK | `specvista-analytics-rn` | Not yet on npm |
| MCP server | None | Not available yet. Use the HTTP API |
| CLI | None | Not available yet. Use `curl` or PowerShell `Invoke-RestMethod` |
| Agent skill | None | Not available yet. Use the rules snippet below |

## 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](https://analytics.specvista.com/docs/get-a-project-key.md) 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:

```markdown
## 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](https://analytics.specvista.com/docs/get-a-project-key.md)
- [Add tracking to a website](https://analytics.specvista.com/docs/track-web.md)
- [Add tracking to a Node.js server](https://analytics.specvista.com/docs/track-node.md)
- [Add tracking to a React Native app](https://analytics.specvista.com/docs/track-react-native.md)
- [Read reports](https://analytics.specvista.com/docs/read-reports.md)
- [Errors](https://analytics.specvista.com/docs/errors.md)