API referenceAPIAvailable

Tracking

Create, inspect, update, rotate, and revoke web-tracking write keys, then resolve browser-safe configuration or an install snippet.

Last reviewed July 25, 2026

Tracking management endpoints use a Vendo API key. The browser configuration endpoint uses the tracking write key itself in X-Write-Key.

List write keys


GET /api/v1/tracking/keys

Requires sources.read. List and detail responses omit the full secret and expose only safe key metadata or a prefix.

Create a write key


POST /api/v1/tracking/keys

Requires sources.write.

Field	Type	Required	Notes
`name`	string	No	1-100 characters
`environment`	string	No	`production`, `staging`, or `development`
`allowedOrigins`	string[]	No	Up to 20 valid origin URLs
`destinations`	object[]	No	Up to 10 destination app configs
`rateLimitEps`	integer	No	Events-per-second limit, 1-10,000
`rateLimitEpd`	integer	No	Events-per-day limit, 1,000-100,000,000
`shopDomain`	string	No	Optional shop/domain context


curl -X POST \
  -H "Authorization: Bearer $VENDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production website",
    "environment": "production",
    "allowedOrigins": ["https://www.example.com"],
    "rateLimitEps": 100
  }' \
  https://app2.vendodata.com/api/v1/tracking/keys

The full write key is returned only by this creation response. Store it as a secret before discarding the response.

Get or update a key


GET   /api/v1/tracking/keys/{id}
PATCH /api/v1/tracking/keys/{id}

GET requires sources.read; PATCH requires sources.write. The update body accepts the create fields plus isActive. shopDomain can also be cleared with null.

Rotate a key


POST /api/v1/tracking/keys/{id}/rotate

Requires sources.manage. Rotation creates a replacement with the same settings, revokes the old key, and returns the new full secret once.

Plan a rotation so every deployed client receives the replacement before it must send another event. The old key stops resolving after rotation.

Revoke a key


DELETE /api/v1/tracking/keys/{id}

Requires sources.delete. Revocation is a soft delete and returns { "success": true } when the account-scoped key is found.

Resolve browser configuration


GET /api/v1/tracking/config
X-Write-Key: YOUR_TRACKING_WRITE_KEY

This endpoint returns browser-safe account configuration, allowed origins, limits, and destination configuration without destination credentials. It supports ETag/If-None-Match and a private five-minute cache. Missing, malformed, inactive, or unknown write keys return 401 INVALID_WRITE_KEY.

Generate an install snippet


GET /api/v1/tracking/snippet?writeKey=...&host=...&async=true

Requires sources.read and verifies that the write key belongs to the authenticated API-key account.

Because this contract places the write key in the query string, call it only from trusted tooling and avoid retaining the URL in logs or analytics. Use the returned snippet in the intended site, then remove the full key from shell history and temporary files.

Errors and account scope

Management endpoints scope every key lookup to the API key’s team account.
Unknown IDs return 404.
Invalid bodies or snippet options return 400.
Config responses include X-Request-Id; include it when reporting an error.