Skip to main content

Guilds API

The Guilds API provides endpoints for managing guilds (communities), member operations, and guild discovery. Guilds are team-based communities that can host tournaments and organize members.

Overview​

The Guilds API enables you to:

  • Discover Guilds: List public guilds and get guild details by ID or slug
  • Guild Membership: Join guilds, list members, get member count, and manage member roles
  • Admin Operations: Get your guild, get guild by admin ID, and perform moderator actions (requires appropriate roles)
  • Guild Tournaments: Create, manage, and launch tournaments for your guild (requires guild owner)

Endpoints Summary​

Guilds​

MethodEndpointAuthenticationDescription
GET/api/v2/guilds/meJWTGet the current user's guild (as admin)
GET/api/v2/guilds/publicNoneList public guilds (paginated)
GET/api/v2/guilds/public/:idNoneGet a public guild by ID
GET/api/v2/guilds/slug/:slugNoneGet a guild by slug
GET/api/v2/guilds/admin/:adminIdJWT + Guild OwnerGet guild by admin user ID

Guild Tournaments (User APIs)​

MethodEndpointAuthenticationDescription
POST/api/v2/guild-tournamentsJWT + OwnerCreate a guild tournament
GET/api/v2/guild-tournaments/myJWT + OwnerList my guild's tournaments
GET/api/v2/guild-tournaments/:idJWT + OwnerGet a guild tournament
GET/api/v2/guild-tournaments/:id/treasuryJWT + OwnerGet tournament treasury
PATCH/api/v2/guild-tournaments/:idJWT + OwnerUpdate a guild tournament
POST/api/v2/guild-tournaments/:id/launchJWT + OwnerLaunch an accepted guild tournament

Authentication​

The Guilds API uses different authentication methods:

Public Endpoints (No Authentication)​

  • GET /api/v2/guilds/public - List public guilds
  • GET /api/v2/guilds/public/:id - Get public guild by ID
  • GET /api/v2/guilds/slug/:slug - Get guild by slug

JWT Token Authentication​

User-specific operations require a JWT token:

Authorization: Bearer user-jwt-token-here
  • Get my guild
  • Join guild
  • Get member count
  • Guild tournament operations (create, list my, get, update, launch)

Role-Based Permissions​

PermissionDescriptionEndpoints
guilds.ownerGuild owner accessList members, get by admin, guild tournaments
guilds.reviewerGuild reviewer/moderatorList all guilds, get guild, get member

Guild Information​

Guilds include:

  • Basic Details: Name, slug, description, logo, website
  • Social Links: Discord, Twitter, and other social media
  • Member Count: Current size of the guild
  • Admin: User ID of the guild owner/administrator

Member Roles​

RoleDescription
adminGuild administrator with full management access
memberRegular guild member

Cursor Pagination​

List endpoints use cursor-based pagination:

  • Size: Number of items per page (1-30)
  • Cursor Navigation: Use key and direction for pagination
  • Sorting: Sort by name, createdAt, or updatedAt
  • Filtering: Filter by name or adminId (list guilds), role (list members)

Error Codes​

CodeDescription
400Bad Request - Invalid parameters or validation error
401Unauthorized - Missing or invalid JWT token
403Forbidden - Insufficient permissions
404Not Found - Guild or member not found
409Conflict - Already a member (when joining)

Quick Start​

Get a Public Guild by Slug​

const response = await fetch("https://api.intraverse.io/api/v2/guilds/slug/my-guild");
const guild = await response.json();
console.log(guild.name, guild.description);

Join a Guild (Authenticated)​

const response = await fetch("https://api.intraverse.io/api/v2/guilds/guild-123/join", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const member = await response.json();

List Public Guilds​

const response = await fetch("https://api.intraverse.io/api/v2/guilds/public?size=10");
const result = await response.json();
console.log(result.data);

Guild Tournaments​

Guild owners can request tournaments for their guild. Tournaments go through a review process (pending → accepted or rejected). Once accepted, the guild owner can launch the tournament.

Tournament statuses: pending, accepted, rejected, launched

Next Steps​