API Endpoints - Sports Buddies

🌟 Overview

This reference provides comprehensive information about all available API endpoints, including request/response formats, authentication requirements, and usage examples.

🔗 Base URL

All API endpoints are relative to: https://api.joinsportsbuddies.app

📚 Authentication

All endpoints require authentication. See our Authentication Guide for details.

👤 Users

Manage user accounts, profiles, and preferences.

GET /v1/users/me

Description: Get current user's profile information

Authentication: Required

Scopes: read

Response Example:

{
  "id": "user_123",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "age": 25,
  "location": {
    "city": "New York",
    "state": "NY",
    "country": "US"
  },
  "sports": [
    {
      "name": "basketball",
      "skill_level": "intermediate",
      "experience_years": 5
    }
  ],
  "verification_status": "verified",
  "created_at": "2025-01-15T10:30:00Z"
}
                

PUT /v1/users/me

Description: Update current user's profile

Authentication: Required

Scopes: write

Request Body:

{
  "first_name": "John",
  "last_name": "Smith",
  "sports": [
    {
      "name": "basketball",
      "skill_level": "advanced"
    }
  ]
}
                

GET /v1/users/{user_id}

Description: Get public profile of another user

Authentication: Required

Scopes: read

Path Parameters:

Parameter	Type	Description
user_id	string	Unique identifier of the user

🎯 BuddyMatch

Find compatible sports buddies using our advanced matching algorithm.

POST /v1/matches/find

Description: Find potential sports buddies based on preferences

Authentication: Required

Scopes: matching

Request Body:

{
  "sports": ["basketball", "tennis"],
  "skill_level": "intermediate",
  "max_distance": 25,
  "availability": ["weekends", "evenings"],
  "age_range": {
    "min": 20,
    "max": 35
  }
}
                

Response Example:

{
  "matches": [
    {
      "user_id": "user_456",
      "compatibility_score": 0.89,
      "common_sports": ["basketball"],
      "distance": 12.5,
      "availability_overlap": 0.75
    }
  ],
  "total_matches": 15,
  "next_page": "eyJpZCI6InVzZXJfNzg5In0="
}
                

GET /v1/matches/recommendations

Description: Get personalized match recommendations

Authentication: Required

Scopes: matching

Query Parameters:

Parameter	Type	Required	Description
limit	integer	No	Number of recommendations (default: 20)
offset	integer	No	Pagination offset (default: 0)

💬 Messaging

Send and receive messages with other users.

POST /v1/messages/send

Description: Send a message to another user

Authentication: Required

Scopes: write

Request Body:

{
  "recipient_id": "user_456",
  "message": "Hey! Want to play basketball this weekend?",
  "type": "text"
}
                

GET /v1/messages/conversations

Description: Get list of conversations

Authentication: Required

Scopes: read

Response Example:

{
  "conversations": [
    {
      "id": "conv_123",
      "participants": ["user_123", "user_456"],
      "last_message": {
        "content": "See you tomorrow!",
        "timestamp": "2025-01-15T14:30:00Z",
        "sender_id": "user_456"
      },
      "unread_count": 1
    }
  ]
}
                

GET /v1/messages/conversations/{conversation_id}

Description: Get messages in a specific conversation

Authentication: Required

Scopes: read

Query Parameters:

Parameter	Type	Required	Description
limit	integer	No	Number of messages (default: 50)
before	string	No	Get messages before this timestamp

📅 Events

Create, manage, and join sports events and activities.

POST /v1/events/create

Description: Create a new sports event

Authentication: Required

Scopes: events

Request Body:

{
  "title": "Weekend Basketball Game",
  "description": "Casual pickup basketball game",
  "sport": "basketball",
  "skill_level": "all_levels",
  "date": "2025-01-25T14:00:00Z",
  "duration": 120,
  "location": {
    "name": "Central Park Basketball Courts",
    "address": "Central Park, New York, NY",
    "coordinates": {
      "latitude": 40.7829,
      "longitude": -73.9654
    }
  },
  "max_participants": 10,
  "price": 0
}
                

GET /v1/events/search

Description: Search for events based on criteria

Authentication: Required

Scopes: read

Query Parameters:

Parameter	Type	Required	Description
sport	string	No	Filter by sport type
location	string	No	Search near this location
date_from	string	No	Events from this date (ISO 8601)
date_to	string	No	Events until this date (ISO 8601)

POST /v1/events/{event_id}/join

Description: Join an event

Authentication: Required

Scopes: write

Request Body:

{
  "message": "I'm in! Looking forward to playing."
}
                

📊 Analytics

Access platform analytics and insights (Enterprise only).

GET /v1/analytics/usage

Description: Get API usage statistics

Authentication: Required

Scopes: admin

Response Example:

{
  "period": "2025-01",
  "total_requests": 15420,
  "unique_users": 1250,
  "endpoints": {
    "/v1/users/me": 3200,
    "/v1/matches/find": 2800,
    "/v1/messages/send": 2100
  }
}
                

🔗 Webhooks

Configure webhooks to receive real-time updates.

POST /v1/webhooks

Description: Create a new webhook

Authentication: Required

Scopes: admin

Request Body:

{
  "url": "https://your-app.com/webhooks/sportsbuddies",
  "events": ["user.created", "message.sent", "event.created"],
  "secret": "your_webhook_secret"
}
                

❌ Error Handling

All endpoints return consistent error responses:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  }
}
                

Common Error Codes

Code	HTTP Status	Description
unauthorized	401	Invalid or expired authentication
forbidden	403	Insufficient permissions
not_found	404	Resource not found
validation_error	400	Invalid request parameters
rate_limit_exceeded	429	Too many requests

⏱️ Rate Limits

API requests are subject to rate limiting to ensure fair usage:

📊 Rate Limit Tiers

Free Tier: 1,000 requests per hour
Basic Tier: 10,000 requests per hour
Professional Tier: 100,000 requests per hour
Enterprise Tier: Custom limits

⚠️ Rate Limit Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: Requests allowed per hour
X-RateLimit-Remaining: Requests remaining in current hour
X-RateLimit-Reset: Time when limits reset (Unix timestamp)

🆘 Getting Help

Need assistance with API endpoints?

📚 Additional Resources

Authentication Guide - Learn how to authenticate
Quick Start Guide - Get up and running quickly
SDKs & Libraries - Official client libraries
Webhooks Guide - Real-time updates

📞 API Support

Technical Support: api-support@joinsportsbuddies.app
Documentation Issues: docs@joinsportsbuddies.app
Response Time: Typically within 24 hours
Status Page: API Status

Explore More Documentation

Discover other helpful guides and resources to get the most out of Sports Buddies.

🎯 Getting Started

Learn the basics of Sports Buddies, create your profile, and make your first connection.

Quick Start Guide Profile Setup Making Connections App Navigation

📱 User Guides

Master all the features and learn how to get the most out of Sports Buddies.

BuddyMatch™ Algorithm Messaging & Communication Events & Meetups Notifications & Settings

🛡️ Safety & Trust

Learn about our PlaySafe™ features, verification process, and how we protect our community.

VerifiedPlayer™ ID Verification PlaySafe™ Safety Features Reporting Issues ShowScore™ Rating System

🤝 Community

Understand our community guidelines, moderation policies, and how to be a great community member.

Community Guidelines Moderation Policies Best Practices Community Events

⚙️ API & Developers

Technical documentation for developers, integrations, and API access.

API Overview Authentication API Endpoints Webhooks

❓ Help & Support

Find answers to common questions and get help when you need it.

Frequently Asked Questions Troubleshooting Contact Support Send Feedback

📋 Policies

Read our terms of service, privacy policy, and other important legal documents.

🔗 API Endpoints

🌟 Overview

🔗 Base URL

📚 Authentication

👤 Users

Response Example:

Request Body:

Path Parameters:

🎯 BuddyMatch

Request Body:

Response Example:

Query Parameters:

💬 Messaging

Request Body:

Response Example:

Query Parameters:

📅 Events

Request Body:

Query Parameters:

Request Body:

📊 Analytics

Response Example:

🔗 Webhooks

Request Body:

❌ Error Handling

Common Error Codes

⏱️ Rate Limits

📊 Rate Limit Tiers

⚠️ Rate Limit Headers

🆘 Getting Help

📚 Additional Resources

📞 API Support

Explore More Documentation

🎯 Getting Started

📱 User Guides

🛡️ Safety & Trust

🤝 Community

⚙️ API & Developers

❓ Help & Support

📋 Policies