API Reference
Space API Reference
Query space information and loyalty points rankings
Overview
The Space API provides access to space information and loyalty points leaderboards.
Core Queries
Get Space Information
Get Loyalty Points Rankings
Variables:
Alternative: Direct Rankings Query
Field Reference
Key Fields
Field | Type | Description |
---|---|---|
id | String! | Space’s unique identifier |
name | String! | Space display name |
description | String | Space description |
loyaltyPointsRanks | LoyaltyPointsRanks | Leaderboard data |
Pagination Parameters
Parameter | Status | Description |
---|---|---|
cursorAfter | ✅ Current | Start pagination after this cursor |
cursorBefore | ✅ Current | Start pagination before this cursor |
sprintId | Optional | Filter by specific sprint |
first | ⚠️ Deprecated | Use cursor-based pagination |
after | ⚠️ Deprecated | Use cursor-based pagination |
LoyaltyPointsRank Fields
Field | Type | Description |
---|---|---|
rank | Int! | User’s position in leaderboard |
points | Int! | User’s total loyalty points |
address | Address | User profile information |
Integration Patterns
Basic Leaderboard Query
Sprint-Specific Rankings
To get rankings for a specific sprint period, include the sprintId
parameter:
Pagination Pattern
- Start with
cursorAfter: null
- Use
pageInfo.endCursor
from response as nextcursorAfter
- Continue until
pageInfo.hasNextPage
isfalse
User Position Lookup
No Direct User Lookup: The B2B API does not provide a direct user position lookup field like addressLoyaltyPoints
. To find a specific user’s rank, you must paginate through the leaderboard pages.
Search Strategy
- Limited Search: Search first 10-20 pages for UI responsiveness
- Background Search: Comprehensive search for analytics
- Cache Results: Store user positions to reduce future searches
- Pagination Required: Use
cursorAfter
/cursorBefore
for efficient traversal
Best Practices
- Pagination: Use cursor-based pagination (
cursorAfter
/cursorBefore
) - Rate Limiting: Add 200-500ms delays between pagination requests
- Caching: Cache leaderboard data for 30-60 seconds
- Search Limits: Limit user searches to reasonable page counts (50-100 pages)
- Sprint Context: Use
sprintId
for time-limited competitions
Common Errors
Error | Cause | Solution |
---|---|---|
Space not found | Invalid space ID | Verify space ID exists |
Invalid sprint ID | Sprint doesn’t exist | Check sprint ID or omit parameter |
Rate limit exceeded | Too many requests | Implement retry logic |
Invalid cursor | Malformed cursor | Start fresh without cursor |
Next Steps
- Loyalty Program Guide - Points implementation
- Leaderboard Guide - Advanced ranking features
- Authentication - Access token setup