Skip to main content

API Reference

This document provides detailed information about all available SplitScreen API endpoints.

Authentication​

All API requests (except client registration and token generation) require a JWT access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Client Management​

Register Client​

POST /v1/client

Register a new client application with the SplitScreen API.

Request Body:

{
  "name": "Your Client Name"
}

Response:

{
  "client_id": "yourclientname-abc123",
  "api_key": "your-api-key-here",
  "client_secret": "your-client-secret-here"
}

Get Access Token​

POST /v1/token

Obtain a JWT access token using your client credentials.

Request Body:

{
  "client_id": "your-client-id",
  "api_key": "your-api-key",
  "client_secret": "your-client-secret"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

User Management​

Bulk Import Users​

POST /v1/users

Import multiple user profiles in a single request (up to 100 users).

Request Body:

[
  {
    "user_id": "user123",
    "display_name": "PlayerOne",
    "genres": ["fps", "strategy"],
    "games": [
      {
        "name": "Counter-Strike 2",
        "playtime_minutes": 1200,
        "achievements_count": 15
      }
    ],
    "schedule": {
      "timezone": "America/New_York",
      "slots": [
        {
          "day": "monday",
          "start_time": "19:00",
          "end_time": "22:00"
        }
      ]
    },
    "location": {
      "country_code": "US",
      "region": "NY"
    },
    "personality": {
      "type": "mbti",
      "value": "INTJ"
    },
    "yee_gamer_motivation": {
      "power": 80,
      "story": 26,
      "design": 21,
      "fantasy": 77,
      "strategy": 75,
      "challenge": 36,
      "community": 19,
      "discovery": 43,
      "completion": 10,
      "excitement": 18,
      "competition": 48,
      "destruction": 67
    },
    "custom_attributes": {
      "skill_level": "expert",
      "preferred_team_size": 5
    }
  }
]

Response:

{
  "message": "Users imported successfully",
  "imported_count": 1
}

Get User Profile​

GET /v1/users/{user_id}

Retrieve a specific user's profile.

Path Parameters:

  • user_id (string): The unique identifier for the user on the client's platform

Response:

{
  "user": {
    "client_user_id": "client123:user123",
    "display_name": "PlayerOne",
    "genres": ["fps", "strategy"],
    "games": [
      {
        "name": "Counter-Strike 2",
        "playtime_minutes": 1200,
        "achievements_count": 15
      }
    ],
    "schedule": {
      "timezone": "America/New_York",
      "slots": [
        {
          "day": "monday",
          "start_time": "19:00",
          "end_time": "22:00"
        }
      ]
    },
    "location": {
      "country_code": "US",
      "region": "NY"
    },
    "personality": {
      "type": "mbti",
      "value": "INTJ"
    },
    "yee_gamer_motivation": {
      "power": 80,
      "story": 26,
      "design": 21,
      "fantasy": 77,
      "strategy": 75,
      "challenge": 36,
      "community": 19,
      "discovery": 43,
      "completion": 10,
      "excitement": 18,
      "competition": 48,
      "destruction": 67
    },
    "custom_attributes": {
      "skill_level": "expert",
      "preferred_team_size": 5
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:45:00Z"
  }
}

List Users​

GET /v1/users

Retrieve a paginated list of user profiles.

Query Parameters:

  • page (integer, optional): Page number (1-based, default: 1)
  • limit (integer, optional): Number of users per page (1-100, default: 10)

Response:

{
  "total": 42,
  "users": [
    {
      "client_user_id": "client123:user123",
      "display_name": "PlayerOne",
      "genres": ["fps", "strategy"],
      "games": [...],
      "schedule": {...},
      "location": {...},
      "personality": {...},
      "custom_attributes": {...},
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z"
    }
  ]
}

Delete User​

DELETE /v1/users/{user_id}

Delete a user's profile from the system.

Path Parameters:

  • user_id (string): The unique identifier for the user on the client's platform

Response:

{
  "message": "User profile deleted"
}

Yee's Gamer Motivation Model​

SplitScreen integrates with Yee's Gamer Motivation Model to provide more accurate matchmaking recommendations. This model analyzes 12 key gaming motivations that drive player behavior and preferences.

What is Yee's Model?​

Yee's Gamer Motivation Model is a research-based framework that measures gaming motivations across 12 dimensions:

  • Power: Desire for status, control, and dominance
  • Story: Interest in narrative and character development
  • Design: Appreciation for aesthetics and creativity
  • Fantasy: Desire for escapism and role-playing
  • Strategy: Preference for tactical thinking and planning
  • Challenge: Seeking difficulty and skill mastery
  • Community: Desire for social interaction and teamwork
  • Discovery: Interest in exploration and learning
  • Completion: Drive to finish games and collect achievements
  • Excitement: Seeking adrenaline and fast-paced action
  • Competition: Desire to win and outperform others
  • Destruction: Enjoyment of chaos and mayhem

Integration with Quantic Foundry​

We have partnered with Quantic Foundry to support the integration of Yee's Gamer Motivation Model survey in your applications. This allows you to:

  1. Collect Motivation Data: Use Quantic Foundry's validated survey to gather user motivation scores
  2. Improve Matchmaking: Provide more accurate recommendations based on gaming psychology
  3. Enhanced User Experience: Help users find players with compatible gaming motivations

How to Use Yee's Model​

To include Yee's gamer motivation data in your user profiles, add the yee_gamer_motivation field with percentile scores (0-100) for each dimension:

{
  "yee_gamer_motivation": {
    "power": 80,
    "story": 26,
    "design": 21,
    "fantasy": 77,
    "strategy": 75,
    "challenge": 36,
    "community": 19,
    "discovery": 43,
    "completion": 10,
    "excitement": 18,
    "competition": 48,
    "destruction": 67
  }
}

Note: Scores are percentiles where 50 represents the average gamer, 80 means higher than 80% of gamers, and 20 means lower than 80% of gamers.

Benefits for Your Users​

  • Better Match Quality: Find players with similar gaming motivations
  • Reduced Toxicity: Match players who enjoy similar play styles
  • Improved Retention: Users are more likely to enjoy playing with compatible teammates
  • Data-Driven Insights: Understand what motivates your users to play

For more information about implementing Yee's Gamer Motivation Model in your application, contact us or visit Quantic Foundry's resources.

Recommendations​

Get User Recommendations​

GET /v1/users/{user_id}/recommendations

Get personalized matchmaking recommendations for a specific user.

Path Parameters:

  • user_id (string): The unique identifier for the user on the client's platform

Query Parameters:

  • count (integer, optional): Maximum number of recommendations to return (1-100, default: 10)

Response:

{
  "recommendations": [
    {
      "client_user_id": "client123:user456",
      "display_name": "PlayerTwo",
      "overall_score": 0.85,
      "score_breakdown": {
        "games": 0.9,
        "schedule": 0.8,
        "location": 0.75,
        "genres": 0.9,
        "personality": 0.85,
        "yee_gamer_motivation": 0.78
      }
    },
    {
      "client_user_id": "client123:user789",
      "display_name": "PlayerThree",
      "overall_score": 0.72,
      "score_breakdown": {
        "games": 0.7,
        "schedule": 0.8,
        "location": 0.65,
        "genres": 0.7,
        "personality": 0.75,
        "yee_gamer_motivation": 0.68
      }
    }
  ]
}

Data Models​

User Profile Structure​

{
  "client_user_id": "string",
  "display_name": "string",
  "genres": ["string"],
  "games": [
    {
      "name": "string",
      "playtime_minutes": "integer",
      "achievements_count": "integer"
    }
  ],
  "anime": [
    {
      "id": "integer",
      "title": "string",
      "genres": ["string"]
    }
  ],
  "manga": [
    {
      "id": "integer",
      "title": "string",
      "genres": ["string"]
    }
  ],
  "schedule": {
    "timezone": "string",
    "slots": [
      {
        "day": "string",
        "start_time": "string",
        "end_time": "string"
      }
    ]
  },
  "location": {
    "country_code": "string",
    "region": "string"
  },
  "personality": {
    "type": "string",
    "value": "string"
  },
  "yee_gamer_motivation": {
    "power": "integer (0-100)",
    "story": "integer (0-100)",
    "design": "integer (0-100)",
    "fantasy": "integer (0-100)",
    "strategy": "integer (0-100)",
    "challenge": "integer (0-100)",
    "community": "integer (0-100)",
    "discovery": "integer (0-100)",
    "completion": "integer (0-100)",
    "excitement": "integer (0-100)",
    "competition": "integer (0-100)",
    "destruction": "integer (0-100)"
  },
  "custom_attributes": "object"
}

Recommendation Structure​

{
  "client_user_id": "string",
  "display_name": "string",
  "overall_score": "float",
  "score_breakdown": {
    "games": "float",
    "schedule": "float",
    "location": "float",
    "genres": "float",
    "personality": "float",
    "yee_gamer_motivation": "float"
  }
}

User Connections​

The User Connections API allows users to send, accept, and decline connection requests, manage their connections, and receive notifications about connection events.

Send Connection Request​

POST /v1/connections/{user_id}/request

Send a connection request to another user.

Path Parameters:

  • user_id (string): The sender's client user ID

Request Body:

{
  "receiver_id": "user456",
  "message": "Hi! I'd like to connect with you."
}

Response:

{
  "message": "Connection request sent successfully",
  "id": 123
}

Accept Connection Request​

POST /v1/connections/{user_id}/accept/{request_id}

Accept a pending connection request from another user.

Path Parameters:

  • user_id (string): The receiver's client user ID
  • request_id (string): The ID of the connection request to accept

Response:

{
  "message": "Connection request accepted successfully"
}

Decline Connection Request​

POST /v1/connections/{user_id}/decline/{request_id}

Decline a pending connection request from another user.

Path Parameters:

  • user_id (string): The receiver's client user ID
  • request_id (string): The ID of the connection request to decline

Response:

{
  "message": "Connection request declined successfully"
}

Get Sent Connection Requests​

GET /v1/connections/{user_id}/sent

Get a paginated list of connection requests sent by the user.

Path Parameters:

  • user_id (string): The sender's client user ID

Query Parameters:

  • page (integer, default: 1): Page number (1-based)
  • per_page (integer, default: 10, max: 50): Items per page
  • status (string, optional): Filter by status (pending, accepted, declined, or all)

Response:

{
  "requests": [
    {
      "id": 123,
      "user": {
        "client_user_id": "user456",
        "display_name": "PlayerTwo"
      },
      "status": "pending",
      "message": "Hi! I'd like to connect with you.",
      "created_at": "2024-01-15T10:30:00Z",
      "responded_at": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_items": 25,
    "per_page": 10
  }
}

Get Received Connection Requests​

GET /v1/connections/{user_id}/received

Get a paginated list of connection requests received by the user.

Path Parameters:

  • user_id (string): The receiver's client user ID

Query Parameters:

  • page (integer, default: 1): Page number (1-based)
  • per_page (integer, default: 10, max: 50): Items per page
  • status (string, optional): Filter by status (pending, accepted, declined, or all)

Response:

{
  "requests": [
    {
      "id": 124,
      "user": {
        "client_user_id": "user789",
        "display_name": "PlayerThree"
      },
      "status": "pending",
      "message": "Let's connect!",
      "created_at": "2024-01-15T11:00:00Z",
      "responded_at": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_items": 1,
    "per_page": 10
  }
}

Get Active Connections​

GET /v1/connections/{user_id}/active

Get a paginated list of active connections for the user.

Path Parameters:

  • user_id (string): The user's client user ID

Query Parameters:

  • page (integer, default: 1): Page number (1-based)
  • per_page (integer, default: 10, max: 50): Items per page

Response:

{
  "connections": [
    {
      "id": 456,
      "connected_user": {
        "client_user_id": "user456",
        "display_name": "PlayerTwo"
      },
      "connected_since": "2024-01-15T12:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_items": 1,
    "per_page": 10
  }
}

Get Connection Notifications​

GET /v1/connections/{user_id}/notifications

Get all notifications related to connection events for the user.

Path Parameters:

  • user_id (string): The user's client user ID

Response:

{
  "notifications": [
    {
      "type": "new_request",
      "connection_request_id": 125,
      "other_user": {
        "client_user_id": "user101",
        "display_name": "PlayerFour"
      },
      "message": "Hi! I'd like to connect with you.",
      "timestamp": "2024-01-15T13:00:00Z",
      "read": false
    },
    {
      "type": "request_accepted",
      "connection_request_id": 123,
      "other_user": {
        "client_user_id": "user456",
        "display_name": "PlayerTwo"
      },
      "message": "Your connection request was accepted!",
      "timestamp": "2024-01-15T12:00:00Z",
      "read": true
    }
  ],
  "unread_count": 1
}

Mark Notification as Read​

POST /v1/connections/{user_id}/notifications/{notification_id}/read

Mark a specific connection notification as read.

Path Parameters:

  • user_id (string): The user's client user ID
  • notification_id (string): The ID of the notification to mark as read

Response:

{
  "message": "Notification marked as read"
}

Remove Connection​

DELETE /v1/connections/{user_id}/{connection_id}

Remove an active connection between users.

Path Parameters:

  • user_id (string): The user's client user ID
  • connection_id (string): The ID of the connection to remove

Response:

{
  "message": "Connection removed successfully"
}

Connection Status Values​

Connection requests can have the following statuses:

  • pending: Request sent but not yet responded to
  • accepted: Request accepted, users are now connected
  • declined: Request declined, no connection created

Notification Types​

Connection notifications include the following types:

  • new_request: A new connection request was received
  • request_accepted: A sent connection request was accepted
  • request_declined: A sent connection request was declined

Error Responses​

All endpoints may return the following error responses:

400 Bad Request​

{
  "error": "Invalid input",
  "message": "Detailed error message"
}

401 Unauthorized​

{
  "error": "Authentication required",
  "message": "Missing or invalid authentication token"
}

404 Not Found​

{
  "error": "Resource not found",
  "message": "User with ID 'user123' does not exist"
}

500 Internal Server Error​

{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

Rate Limits​

  • Client Registration: 10 requests per hour
  • Token Generation: 100 requests per hour
  • User Operations: 1000 requests per hour
  • Recommendations: 500 requests per hour
  • Connections: 1000 requests per hour

Best Practices​

  1. Store Credentials Securely: Keep your API key and client secret safe
  2. Cache Tokens: JWT tokens expire after 1 hour, cache and reuse them
  3. Handle Errors Gracefully: Implement proper error handling for all API calls
  4. Use Pagination: For large datasets, use the pagination parameters
  5. Validate Input: Ensure all required fields are provided before making requests
  6. Manage Connection States: Track connection request statuses and handle user responses appropriately
  7. Handle Notifications: Implement real-time notification handling for connection events
  8. Respect User Privacy: Only send connection requests to users who have opted in to receiving them