# Build against documented Virent interfaces.

> Virent SDKs, keys and the OpenAPI specification for browser analytics ingest, AI crawler ingest and the analytics read API.

Canonical: https://virent.app/docs/api
Last updated: 2026-07-29

Browser analytics, server crawler ingest and the analytics read API, with an OpenAPI specification for every supported HTTP operation.

- [Read installation guides](/docs#installation)

- [Contact developer support](/contact)

## Supported integration paths

### Browser script

Use the site-wide browser script when the implementation needs standard pageview and session collection with minimal custom code.

The script uses the site's publishable write key. It must not receive the server ingest secret.
### Browser SDK

Use @virent.app/sdk/browser when the implementation needs explicit initialization, pageviews, custom events, customer-chosen identity data, or goals.

Use examples from the tested framework guides. Do not infer exports from old homepage snippets.
### Framework and server integrations

Use the documented framework helper or request-layer pattern to capture AI crawler requests. Keep the full ingest secret in a server environment variable.
### HTTP interfaces

Virent's supported HTTP operations are described in the [OpenAPI specification](/openapi.json): payloads, authentication, idempotency, size limits, errors and rate limits. A route that is not in the specification is internal.
### Authorized data access

Plans that include the read API can read analytics with a private API key. The read operations in the OpenAPI specification are the supported surface; do not assume that an internal application endpoint is a supported customer API.

## @virent.app/sdk

The current release is `0.3.1`. Install it with `pnpm add @virent.app/sdk@^0.3.0`.

| Entry point | Runs in | Exports |
| --- | --- | --- |
| `@virent.app/sdk/browser` | Browser | `initVirent`, `pageview`, `trackEvent`, `identify`, `trackGoal`, `resetVirent`, `createVirentBrowserClient` |
| `@virent.app/sdk/server` | Server | `createVirentBotTracker`, `classifyBotUserAgent` |
| `@virent.app/sdk/next` | Next.js server files | `createVirentBotProxy` (crawler capture in `proxy.ts`), `withVirentBotProxy` (wraps an existing proxy), `createVirentAnalyticsProxy` (first-party route handler) |

Usage: [Human Analytics](/docs/analytics/human-analytics), [AI Crawler Analytics](/docs/analytics/ai-crawlers), [First-party analytics](/docs/installation/first-party) and the [framework guides](/docs#installation).

## Browser script

`https://app.virent.app/js/script.js` takes these attributes: `data-write-key` (required), `data-allow-localhost`, `data-consent`, `data-respect-do-not-track`, `data-api` (relay path or origin) and `data-api-url` (full ingest URL, which wins over `data-api`). It exposes `window.virent` with the commands `consent`, `pause`, `resume`, `pageview` and `event`. See [Human Analytics](/docs/analytics/human-analytics#script-options).

## Authentication model

### Publishable keys

Publishable keys identify permitted browser ingest configuration. They may appear in client code but should still be limited to the intended site and origin policy.
### Server secrets

Server ingest secrets authenticate protected server-to-server writes. Store them in environment variables or the hosting platform's secret store. Never include them in browser bundles, public repositories, screenshots, support messages, or documentation examples.
### API keys

Private API keys (`vnt_sk_`) read one workspace's data through the read API on plans that include it. Owners, admins and developers create, list and revoke them in Settings → Connection; the full key is shown once. A key works only in the workspace it was created in, expires a year after it is created, and stops working when the member who created it leaves the workspace or loses API access. Send it in the `x-api-key` header.

## OpenAPI specification

[`https://virent.app/openapi.json`](/openapi.json) describes the Virent API in OpenAPI 3.1. Every operation has an `operationId`, a description, typed parameters and response schemas, so API clients and AI agents can import it directly.

| Operation | Endpoint | Authentication |
| --- | --- | --- |
| `ingestBrowserEvents` | `POST /v1/ingest/batch` | Publishable key (`vha_pk_`), from an allowed origin |
| `ingestCrawlerRequest` | `POST /v1/ingest/bot` | Server secret (`vha_sk_`) |
| `getAnalyticsOverview` | `GET /v1/analytics/overview` | Private API key (`vnt_sk_`) |
| `getAnalyticsTimeseries` | `GET /v1/analytics/timeseries` | Private API key (`vnt_sk_`) |
| `getAnalyticsTraffic` | `GET /v1/analytics/traffic` | Private API key (`vnt_sk_`) |
| `getAnalyticsPages` | `GET /v1/analytics/pages` | Private API key (`vnt_sk_`) |
| `getAnalyticsReferrers` | `GET /v1/analytics/referrers` | Private API key (`vnt_sk_`) |
| `getAnalyticsVisitors` | `GET /v1/analytics/visitors` | Private API key (`vnt_sk_`) |

Read operations answer 402 when the workspace's plan does not include the read API. Rate limits and error bodies are in each operation's responses. To call these operations from a terminal or an AI agent without writing code, use the [Virent CLI](/docs/cli).

## Rate limits

Ingest is limited per key and visitor network: 120 requests a minute for browser ingest and 240 for crawler ingest, plus a per-website events-per-minute ceiling that scales with the plan. Every ingest response reports the request bucket in the IETF `RateLimit-Policy` and `RateLimit` fields, alongside `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`:

```http
RateLimit-Policy: "browser";q=120;w=60
RateLimit: "browser";r=119;t=55
```

The read API allows 300 requests a minute per client IP, counted before the key is checked. Every read response, including 401s, reports it the same way:

```http
RateLimit-Policy: "read";q=300;w=60
RateLimit: "read";r=299;t=55
```

`q` is the quota, `w` the window in seconds, `r` the requests left and `t` the seconds until the window resets. A throttled request answers 429 with `Retry-After` in seconds; wait at least that long before retrying.

## Versioning and deprecation

- The major version is in the path: every operation is under `/v1`.
- Backward-compatible changes ship within `/v1` without notice: new operations, new optional parameters and new response fields. Ignore fields you do not recognize.
- Breaking changes ship only under a new major version, such as `/v2`. The previous version keeps working until its sunset date.
- A deprecated operation is marked `deprecated: true` in the OpenAPI specification and announced on this page. Its responses carry a `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) with the date it was deprecated and a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) with the date it stops working.
- Virent gives at least 6 months between deprecation and sunset.

No operation is deprecated today.

## Current developer guidance

For an implementation today:

1. choose the relevant framework guide;
2. use the exact browser or server pattern documented there;
3. create the correct key in the workspace;
4. store server secrets outside committed source;
5. verify the event path;
6. contact Virent before building against an endpoint that is not in the OpenAPI specification.

## Frequently asked questions

### Can we use internal /api/* routes as a public API?

No. Internal application routes are not a supported public contract unless they are explicitly documented here.

### Is every /v1/* route public?

No. Only the operations in the OpenAPI specification are supported. A versioned path alone does not define support, authorization, or customer availability.

### Where should we get code samples?

Use the public framework installation guides and the released package documentation. Samples must be tested against the current package version.

### How do we request an integration that is not documented?

Contact Virent with the framework, hosting layer, data direction, expected volume, and intended use. Do not send credentials or customer data.

## Use a supported path before building a custom one.

Start with the framework guides. If your architecture needs an interface the OpenAPI specification does not cover, contact Virent first.

- [Read installation guides](/docs#installation)

- [Contact developer support](/contact)