API Getting Started

Base URL

All API requests are made to:

https://api.vslstats.com/v1

All requests and responses use JSON. Set the Content-Type: application/json and Accept: application/json headers on all requests.

Authentication

The VSLStats API uses Bearer token authentication. Generate an API key from your account settings:

1. Go to Settings → API Keys.
2. Click Generate New Key. Give it a descriptive label (e.g., "Zapier integration" or "Custom dashboard").
3. Copy the key immediately - it's only shown once for security. Store it in your password manager or secrets vault.
4. Include the key in every request as an Authorization header.

# Example: authenticated request using curl
curl -X GET https://api.vslstats.com/v1/projects \
  -H "Authorization: Bearer vsl_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Your First Request

List all projects in your workspace:

GET /v1/projects

// Response
{
  "data": [
    {
      "id": "proj_abc123",
      "name": "Main VSL - Product Launch",
      "created_at": "2025-08-01T10:00:00Z",
      "video_count": 3
    }
  ],
  "meta": { "total": 1, "page": 1 }
}

Available Endpoints

Projects

• GET /v1/projects - List all projects.
• GET /v1/projects/:id - Get a single project.
• POST /v1/projects - Create a project.
• PATCH /v1/projects/:id - Update project settings.
• DELETE /v1/projects/:id - Delete a project.

Videos

• GET /v1/projects/:id/videos - List videos in a project.
• GET /v1/videos/:id - Get video details and settings.
• PATCH /v1/videos/:id - Update video settings (title, player config, etc.).

Analytics

• GET /v1/videos/:id/analytics - Video-level stats (views, completion rate, play rate).
• GET /v1/videos/:id/analytics/timeline - Engagement data by second/minute for heatmaps.
• GET /v1/projects/:id/analytics - Project-level aggregate stats.

Analytics endpoints accept start_date and end_date query parameters (ISO 8601 format) to filter by date range.

Conversions

• GET /v1/videos/:id/conversions - List conversion events for a video.
• POST /v1/conversions - Manually record a conversion (for server-to-server use cases).

Webhooks

VSLStats can send webhook notifications to your server when key events occur. This allows real-time integrations - for example, triggering a CRM update when a video is completed.

Registering a Webhook

POST /v1/webhooks
{
  "url": "https://yourdomain.com/vslstats-webhook",
  "events": ["video.play", "video.complete", "conversion.created"]
}

Available Webhook Events

• video.play - Fired when a visitor starts a video.
• video.progress - Fired at 25%, 50%, 75% watch milestones.
• video.complete - Fired when a video reaches the end.
• conversion.created - Fired when a conversion event is recorded.
• ab_test.winner_determined - Fired when an A/B test reaches statistical significance.

Verifying Webhook Signatures

Each webhook payload includes an X-VSLStats-Signature header - an HMAC-SHA256 signature of the raw request body using your webhook secret. Always verify this signature before processing the payload.

# Python example
import hmac, hashlib

def verify_signature(payload_body, secret, signature_header):
    expected = hmac.new(
        secret.encode(), payload_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Rate Limits

The API enforces the following rate limits per API key:

• Standard endpoints (projects, videos, settings): 120 requests / minute.
• Analytics endpoints: 60 requests / minute (heavier database queries).
• Conversion ingestion (POST /v1/conversions): 300 requests / minute.

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp when the window resets).

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your client to handle this gracefully.

SDKs & Libraries

Official SDKs are in development for Node.js and Python. In the meantime, the API is straightforward to use with any HTTP client. Full OpenAPI / Swagger documentation is available at https://api.vslstats.com/v1/docs for auto-generating client code in your language of choice.