Skip to main content

API Schemas

This section contains reference schemas for request and response objects used throughout the Intraverse Backend API.

Overview​

The API schemas define the structure and data types for:

  • Request Payloads: Data sent to API endpoints using class-validator decorators
  • Response Objects: Data returned from API endpoints
  • Common Objects: Reusable data structures like pagination
  • Error Responses: Standard error message formats

Authentication Overview​

The Intraverse Backend API uses different authentication methods:

Public APIs (No Authentication)​

  • All Tournament APIs (/api/v2/tournament/...)
  • All Drop APIs (/api/v2/drop/...)
  • GET /api/v2/game-point/game-client/{userId}/{roundId} (user score by user ID)

Game Key Authentication​

  • Header: x-game-key: <game_key>
  • Used by: Set New Game Point API

JWT Token Authentication​

  • Header: Authorization: Bearer <jwt_token> (often together with x-game-key for game-client routes)
  • Used by: Authenticated Get User Game Score (GET .../game-client/{roundId})

Example Requests​

// Public API (no authentication)
const publicResponse = await fetch("https://api.intraverse.io/api/v2/tournament/game/my-game?size=10");

// Game key authentication
const gameResponse = await fetch("https://api.intraverse.io/api/v2/game-point/", {
  method: "POST",
  headers: {
    "x-game-key": "your-game-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

// JWT + game client key (current user score)
const userResponse = await fetch("https://api.intraverse.io/api/v2/game-point/game-client/round-123", {
  headers: {
    Authorization: "Bearer jwt-token",
    "x-game-key": "your-game-client-key",
  },
});

// Public: score for a specific user ID
const publicScoreResponse = await fetch(
  "https://api.intraverse.io/api/v2/game-point/game-client/user-id-here/round-123",
);

Schema Categories​

Game Point Schemas​

Schemas for game point APIs:

Tournament Schemas​

Schemas for tournament APIs:

Guild Schemas​

Schemas for guild APIs:

Drop Schemas​

Schemas for drop APIs:

Schema Format​

All schemas are documented using:

  • Class-Validator Decorators: Actual validation rules from the codebase
  • TypeScript Types: Type definitions matching the DTOs
  • Examples: Practical usage examples
  • Field Descriptions: Detailed explanations of each field

Common Patterns​

Pagination Format​

The API uses cursor-based pagination with the following structure:

interface PaginationRequestPayload {
  size: number; // Number of items per page (1-30)
  key?: string; // Cursor for pagination
  direction?: "forward" | "backward"; // Pagination direction
  order?: "asc" | "desc"; // Sort order
  orderBy?: string; // Field to sort by
  query?: PaginationQueryItem[]; // Filter queries
}

interface PaginationResponsePayload<T> {
  current: PaginationRequestPayload;
  previous?: PaginationRequestPayload | null;
  next?: PaginationRequestPayload | null;
  data: T[];
}

Standard Response Format​

// Success Response (varies by endpoint)
{
  data: T; // Response data structure varies by endpoint
}
// OR
{
  message: string; // Simple message response
}

// Error Response (consistent across all endpoints)
{
  message: string; // Error description
  status: number; // HTTP status code
}

Data Types​

TypeDescriptionExample
stringText data"hello world"
numberNumeric data42 or 3.14
booleanTrue/false valuestrue or false
arrayOrdered list of values[1, 2, 3]
objectKey-value pairs{"key": "value"}
nullNull valuenull

Validation Rules​

Common validation rules applied to schemas:

  • Required Fields: Fields without @IsOptional() decorator
  • String Length: @MinLength() and @MaxLength() constraints
  • Number Ranges: @Min() and @Max() constraints
  • Enum Values: @IsEnum() with restricted values
  • Nested Validation: @ValidateNested() for complex objects
  • Array Validation: @IsArray() with item validation

Next Steps​