Skip to main content

List Public Guilds

Retrieve a paginated list of all public guilds. No authentication required.

Endpoint​

GET /api/v2/guilds/public

Authentication​

This endpoint is public and does not require authentication.

Description​

Returns a paginated list of public guilds using cursor-based pagination. You can filter by name or admin ID and sort by various fields.

Query Parameters​

ParameterTypeRequiredDescription
sizenumberYesNumber of items per page (min: 1, max: 30)
keystringNoCursor key for pagination
directionstringNoCursor direction: forward or backward
orderstringNoSort order: asc or desc
orderBystringNoField to sort by: name, createdAt, updatedAt
namestringNoFilter by guild name (partial match)
adminIdstringNoFilter by admin user ID

Request Examples​

Basic Request​

GET /api/v2/guilds/public?size=10

With Filtering​

GET /api/v2/guilds/public?size=10&name=Elite

With Sorting​

GET /api/v2/guilds/public?size=10&orderBy=name&order=asc

With Cursor Pagination​

GET /api/v2/guilds/public?size=10&key=guild-123&direction=forward

Response​

Success Response (200)​

{
  "current": {
    "size": 10,
    "key": null,
    "direction": null,
    "order": "asc",
    "orderBy": "name",
    "query": null
  },
  "previous": null,
  "next": {
    "size": 10,
    "key": "guild-456",
    "direction": "forward",
    "order": "asc",
    "orderBy": "name",
    "query": null
  },
  "data": [
    {
      "id": "guild-123",
      "slug": "elite-gamers",
      "name": "Elite Gamers Guild",
      "description": "A community for competitive gamers",
      "logo": "https://example.com/logo.png",
      "website": "https://elitegamers.com",
      "social": [
        {
          "service": "DISCORD",
          "username": "elitegamers"
        }
      ],
      "size": 42,
      "adminId": "user-456",
      "createdAt": 1672531200000,
      "updatedAt": 1704067200000
    }
  ]
}

Error Response (400)​

{
  "message": "Invalid request parameters",
  "status": 400
}

Response Fields​

Pagination Fields​

FieldTypeDescription
currentobjectCurrent pagination parameters
previousobjectPrevious page parameters (null if first)
nextobjectNext page parameters (null if last)
dataarrayArray of guild objects

Guild Data Fields​

FieldTypeDescription
idstringUnique guild identifier
slugstringURL-friendly guild identifier
namestringGuild name
descriptionstringGuild description
logostringGuild logo URL (optional)
websitestringGuild website URL (optional)
socialobject[]Social media links (optional)
sizenumberCurrent member count
adminIdstringUser ID of the guild administrator
createdAtnumberCreation timestamp (Unix ms)
updatedAtnumberLast update timestamp (Unix ms)

Usage Example​

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

console.log(`Found ${result.data.length} guilds`);

result.data.forEach((guild) => {
  console.log(`${guild.name} (${guild.slug}) - ${guild.size} members`);
});

// Handle pagination
if (result.next) {
  const nextPage = await fetch(
    `https://api.intraverse.io/api/v2/guilds/public?size=10&key=${result.next.key}&direction=forward`,
  );
  // Process next page...
}

Next Steps​