API Overview

Getting started with the Wintro Customer API

The Wintro Customer API lets you programmatically access your company’s referral data. Use it to build custom leaderboards, dashboards, reports, or integrations with your internal tools.

Base URL

https://app.wintro.ai/api/v1

Authentication

All requests must include a Bearer token in the Authorization header:

curl -H "Authorization: Bearer wintro_abc123..." \
  https://app.wintro.ai/api/v1/leaderboard

Tokens are prefixed with wintro_ and can be created by a company admin under Settings > API Tokens. Each token is scoped to a specific company and set of permissions.

Scopes

When creating a token, select which endpoints it can access:

Scope	Endpoint	Description
leaderboard:read	/api/v1/leaderboard	Employee leaderboard data

Need access to more data? Reach out to your Wintro contact and we’ll work with you to enable additional endpoints tailored to your needs.

Rate Limiting

All endpoints enforce a rate limit of 100 requests per 60 seconds per token.

When the limit is exceeded, the API returns a 429 status. Rate limit headers are included in every response:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets

Response Format

All successful responses follow this structure:

{
  "data": [ ... ],
  "meta": {
    "generatedAt": "2026-03-16T12:00:00.000Z",
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "totalItems": 42,
      "totalPages": 5
    }
  }
}

Error Format

All errors follow a consistent structure:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}

Status	Code	Description
400	BAD_REQUEST	Invalid query parameters
401	UNAUTHORIZED	Missing, invalid, or revoked token
403	MISSING_SCOPE	Token lacks the required scope for this endpoint
429	RATE_LIMITED	Too many requests
500	INTERNAL_ERROR	Unexpected server error

Pagination

Endpoints that return lists support cursor-free page-based pagination:

Parameter	Default	Max	Description
page	1	-	Page number (starts at 1)
pageSize	varies	varies	Items per page (see endpoint docs)

Creating an API Token

1. Go to Settings > API in the Wintro dashboard
2. Click Create Token
3. Enter a name and select the scopes you need
4. Copy the token immediately, it is only shown once

To revoke a token, click Revoke next to it in the token list.