API Documentation

Access ASA Server List data programmatically with our public REST API

Getting Started

Our public API is free to use and does not require authentication for basic endpoints. Rate limiting is applied to prevent abuse.

Base URL:

https://asaservers.net/api/public

OpenAPI 3.1 specification Test public status endpoint

The OpenAPI document is the versioned source of truth for public and authenticated endpoints. A 503 response means current directory data is temporarily unavailable and clients should retry with backoff.

Owner API authentication

Create credentials in API Key Settings, then combine the returned key and one-time secret.

curl -H "Authorization: Bearer <key>.<secret>" \
  "https://asaservers.net/api/v1/servers?onlineOnly=true&sortBy=currentPlayers"

Endpoints

GET /api/public/servers

Retrieve a list of all servers with pagination and filtering.

Query Parameters:

page (optional) - Page number (default: 1)

limit (optional) - Items per page (default: 20, max: 100)

search (optional) - Search by server name

map (optional) - Filter by map name

Example Request:

GET https://asaservers.net/api/public/servers?page=1&limit=20

Example Response:

{
  "servers": [
    {
      "id": "server-id",
      "name": "Server Name",
      "ipAddress": "127.0.0.1",
      "gamePort": 7777,
      "currentPlayers": 20,
      "maxPlayers": 70,
      "isOnline": true,
      "map": "TheIsland",
      "description": "Server description",
      "totalVotes": 150,
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

GET /api/public/servers/:id

Get detailed information about a specific server.

URL Parameters:

id - Server ID

Example Request:

GET https://asaservers.net/api/public/servers/server-id

Example Response:

{
  "id": "server-id",
  "name": "Server Name",
  "ipAddress": "127.0.0.1",
  "gamePort": 7777,
  "queryPort": 7778,
  "currentPlayers": 20,
  "maxPlayers": 70,
  "isOnline": true,
  "map": "TheIsland",
  "description": "Detailed server description",
  "rates": "xp:2,harvest:3,taming:5",
  "mods": "mod1,mod2",
  "discordUrl": "https://discord.gg/...",
  "website": "https://example.com",
  "totalVotes": 150,
  "version": "1.0.0",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-20T00:00:00.000Z"
}

GET /api/public/stats

Get overall platform statistics.

Example Request:

GET https://asaservers.net/api/public/stats

Example Response:

{
  "totalServers": 250,
  "onlineServers": 230,
  "totalPlayers": 5420,
  "totalVotes": 125000
}

POST /api/billing/checkout

Create a Stripe checkout session for subscription upgrades. Requires authentication.

Request Body:

tier - Subscription tier (standard, premium, enterprise)

Example Request:

POST https://asaservers.net/api/billing/checkout
Content-Type: application/json

{
  "tier": "premium"
}

Example Response:

{
  "sessionId": "cs_test_...",
  "url": "https://checkout.stripe.com/..."
}

GET /api/auctions

Get list of active auctions for featured placements.

Query Parameters:

status (optional) - active, completed, canceled

tier (optional) - standard, premium, enterprise

Example Request:

GET https://asaservers.net/api/auctions?status=active

POST /api/auctions/:id/bid

Place a bid on an active auction. Requires authentication.

Request Body:

bidAmount - Bid amount in cents (must be higher than current highest bid)

Example Request:

POST https://asaservers.net/api/auctions/auction-id/bid
Content-Type: application/json

{
  "bidAmount": 10000
}

POST /api/servers/:id/vote

Submit a vote for a server. No authentication required.

Request Body:

visitorId - Unique visitor identifier (10-100 chars)

username (optional) - Voter username

steamId (optional) - Steam ID

Example Request:

POST https://asaservers.net/api/servers/server-id/vote
Content-Type: application/json

{
  "visitorId": "visitor-abc123xyz",
  "username": "PlayerName",
  "steamId": "76561198000000000"
}

Note:

Votes have a 24-hour cooldown per visitor. Check vote status with GET /api/servers/:id/vote?visitorId=visitor-id

POST /api/servers/:id/favorite

Add a server to your favorites. Requires authentication.

Example Request:

POST https://asaservers.net/api/servers/server-id/favorite

DELETE /api/servers/:id/favorite

Remove a server from your favorites. Requires authentication.

Example Request:

DELETE https://asaservers.net/api/servers/server-id/favorite

GET /api/user/profile

Get current user profile information. Requires authentication.

Example Request:

GET https://asaservers.net/api/user/profile

Example Response:

{
  "id": "user-id",
  "email": "user@example.com",
  "username": "username",
  "avatarUrl": "https://...",
  "steamId": "76561198000000000",
  "discordId": "123456789",
  "isAdmin": false,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "_count": {
    "ownedServers": 5,
    "votes": 42
  }
}

GET /api/user/servers

Get servers owned by the current user. Requires authentication.

Query Parameters:

page (optional) - Page number (default: 1)

limit (optional) - Items per page (default: 10)

Example Request:

GET https://asaservers.net/api/user/servers?page=1&limit=10

GET /api/user/favorites

Get your favorite servers. Requires authentication.

Example Request:

GET https://asaservers.net/api/user/favorites

GET /api/user/api-keys

List your API keys. Requires authentication.

Example Request:

GET https://asaservers.net/api/user/api-keys

POST /api/user/api-keys

Create a new API key. Requires authentication.

Request Body:

name - Name for your API key

Example Request:

POST https://asaservers.net/api/user/api-keys
Content-Type: application/json

{
  "name": "My App"
}

Authentication

Some endpoints require authentication via NextAuth session. To authenticate:

Log in with email/password, Discord, or Steam
Your session will be maintained automatically
Unauthenticated requests to protected endpoints will receive a 401 Unauthorized response

API keys can be created and revoked in API Key Settings for authenticated owner integrations.

Rate Limiting

Public and authenticated endpoints are protected by deployment-level fair-use controls. Limits may vary by traffic conditions and API-key tier.

Vote cooldown: 24 hours per visitor per server
Contact form: 5 submissions per hour per IP
Cache read-only directory responses when possible

A 429 response includes a rate-limit error; retry with exponential backoff. A 503 means current directory data is unavailable and must not be interpreted as an empty result.

Response Codes

200Success - Request completed successfully

400Bad Request - Invalid parameters

404Not Found - Resource does not exist

429Too Many Requests - Rate limit exceeded

500Internal Server Error - Something went wrong

Common Use Cases

Voting for a Server

// Generate a unique visitor ID (e.g., from browser fingerprint)
const visitorId = generateUniqueId();

const response = await fetch('https://asaservers.net/api/servers/server-id/vote', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    visitorId: visitorId,
    username: 'PlayerName'
  })
});

const result = await response.json();
if (response.status === 429) {
  console.log('Vote cooldown active:', result.nextVoteAt);
}

Getting User Profile (Authenticated)

// After user is logged in
const response = await fetch('https://asaservers.net/api/user/profile');
const user = await response.json();
console.log(user.username, user.ownedServers);

Filtering Servers

// Get PvP servers with high multipliers
const params = new URLSearchParams({
  gameMode: 'PvP',
  minMultiplier: '5',
  onlineOnly: 'true',
  sortBy: 'totalVotes',
  limit: '20'
});

const response = await fetch('https://asaservers.net/api/servers?' + params);
const data = await response.json();

Code Examples

JavaScript / Node.js

const response = await fetch('https://asaservers.net/api/public/servers?page=1&limit=20');
const data = await response.json();
console.log(data.servers);

Python

import requests

response = requests.get('https://asaservers.net/api/public/servers', params={'page': 1, 'limit': 20})
data = response.json()
print(data['servers'])

cURL

curl "https://asaservers.net/api/public/servers?page=1&limit=20"

Server Filtering Parameters

The /api/servers endpoint supports advanced filtering:

gameModeFilter by game mode: PvP, PvE, or PvPvE

mapFilter by map name (e.g., TheIsland, Ragnarok)

regionFilter by server region

tagsFilter by comma-separated tags

onlineOnlyShow only online servers (true/false)

justWipedShow recently wiped servers (true/false)

minMultiplierMinimum XP/Taming/Harvest multiplier

maxMultiplierMaximum XP/Taming/Harvest multiplier

sortBySort field: totalVotes, monthlyVotes, currentPlayers, createdAt

sortOrderSort direction: asc or desc

Need Help?

If you have questions about the API or need support, please contact us.

Contact Support