API Documentation

Complete REST API documentation for ASA Server List. 50+ endpoints for servers, users, auctions, and more.

Getting Started

Our API provides access to server listings, user management, voting, auctions, and more. Public endpoints are free to use. Authenticated endpoints require a session or API key.

Public Base URL:

https://asaservers.net/api/public

Authenticated Base URL:

https://asaservers.net/api

Public 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/servers/:id/vote

Submit a vote for a server. 24-hour cooldown per visitor.

Request Body:

{
  "visitorId": "unique-visitor-id",
  "username": "PlayerName",
  "steamId": "76561198123456789"
}

Example Response (Success):

{
  "success": true,
  "message": "Vote recorded successfully",
  "webhookSent": false,
  "nextVoteAt": "2026-01-23T13:45:00.000Z"
}

Example Response (Cooldown):

{
  "error": "Vote cooldown active",
  "cooldownRemaining": 3600000,
  "nextVoteAt": "2026-01-23T13:45:00.000Z",
  "message": "You can vote again in 1 hours"
}

GET /api/servers/:id/vote

Check vote cooldown status for a visitor.

Query Parameters:

visitorId (required) - Visitor ID

Example Response:

{
  "canVote": true,
  "cooldownRemaining": 0
}

Authenticated Endpoints

POST /api/servers/:id/favorite

Add a server to user favorites. Requires authentication.

Authentication:

Requires valid session

Example Response:

{
  "id": "favorite-id",
  "userId": "user-id",
  "serverId": "server-id",
  "createdAt": "2026-01-22T13:45:00.000Z"
}

DELETE /api/servers/:id/favorite

Remove a server from user favorites.

Example Response:

{
  "success": true
}

GET /api/user/profile

Get current user profile information.

Example Response:

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

GET /api/user/favorites

Get user's favorite servers.

Example Response:

{
  "favorites": [
    {
      "id": "server-id",
      "name": "Server Name",
      "ipAddress": "127.0.0.1",
      "gamePort": 7777,
      "currentPlayers": 20,
      "maxPlayers": 70,
      "isOnline": true,
      "map": "TheIsland"
    }
  ]
}

GET /api/user/servers

Get servers owned by current user with pagination.

Query Parameters:

page (optional) - Page number (default: 1)
limit (optional) - Items per page (default: 10)

Example Response:

{
  "servers": [
    {
      "id": "server-id",
      "name": "My Server",
      "ipAddress": "127.0.0.1",
      "gamePort": 7777,
      "isOnline": true,
      "totalVotes": 150,
      "monthlyVotes": 45,
      "recentVotes": 12
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1
  }
}

GET /api/user/api-keys

List all API keys for the current user.

Example Response:

{
  "apiKeys": [
    {
      "id": "key-id",
      "name": "Production Key",
      "key": "sk_abc123def456...",
      "tier": "standard",
      "rateLimit": 100,
      "isActive": true,
      "lastUsedAt": "2026-01-22T10:30:00.000Z",
      "createdAt": "2026-01-15T00:00:00.000Z"
    }
  ]
}

POST /api/user/api-keys

Create a new API key. Secret is only returned once.

Request Body:

{
  "name": "My API Key"
}

Example Response:

{
  "id": "key-id",
  "name": "My API Key",
  "key": "sk_abc123def456...",
  "secret": "secret_xyz789...",
  "tier": "free",
  "rateLimit": 10,
  "isActive": true,
  "createdAt": "2026-01-22T13:45:00.000Z"
}

POST /api/servers

Add a new server to the listing. Requires authentication.

Request Body:

{
  "name": "Server Name",
  "description": "Server description",
  "ipAddress": "127.0.0.1",
  "queryPort": 27015,
  "gamePort": 7777,
  "gameMode": "PvP",
  "website": "https://example.com",
  "discordUrl": "https://discord.gg/...",
  "region": "US-East",
  "tags": "pvp,hardcore"
}

Example Response:

{
  "server": {
    "id": "server-id",
    "name": "Server Name"
  },
  "verificationToken": "token-xyz...",
  "message": "Server added successfully"
}

PATCH /api/servers/:id

Update server details. Owner or admin only.

Request Body (all optional):

{
  "name": "Updated Name",
  "description": "Updated description",
  "gameMode": "PvE",
  "website": "https://newsite.com",
  "discordUrl": "https://discord.gg/...",
  "bannerUrl": "https://...",
  "rates": "xp:2,harvest:3,taming:5",
  "mods": "mod1,mod2"
}

DELETE /api/servers/:id

Delete a server. Owner or admin only.

Example Response:

{
  "message": "Server deleted"
}

Other Endpoints

The following endpoint categories are also available:

  • Server Features: `/api/servers/:id/claim`, `/api/servers/:id/compare`, `/api/servers/:id/featured`, `/api/servers/:id/mods`, `/api/servers/:id/notifications`, `/api/servers/:id/player-history`, `/api/servers/:id/rcon`, `/api/servers/:id/reports`, `/api/servers/:id/wipe-history`
  • User Management: `PATCH /api/user/profile`, `/api/user/subscription`, `/api/user/notification-preferences`, `/api/user/unlink/discord`, `/api/user/unlink/steam`
  • Auctions: `GET /api/auctions`, `POST /api/auctions/:id/bid`, `GET /api/ad-placements`, `GET /api/ad-placements/:location`
  • Admin: `/api/admin/servers`, `/api/admin/users`, `/api/admin/stats`, `/api/admin/ad-slots`
  • Utilities: `POST /api/contact`, `GET /api/servers/suggestions`

For complete details on all endpoints, please refer to the API audit report or contact support.

Authentication

Session-Based Authentication:

  • 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 Key Authentication: Create API keys at `/api/user/api-keys` for programmatic access. Include the key in your requests for custom rate limits based on your subscription tier.

Rate Limiting

To ensure fair usage and prevent abuse, the following rate limits apply:

  • Request Rate Limits: 100 requests per minute per IP, 1000 per hour per IP
  • Vote Cooldown: 24 hours per visitor per server
  • Contact Form: 5 submissions per hour per IP
  • API Key Tiers: Free (10 req/min), Standard (100 req/min), Premium (1000 req/min), Enterprise (10000 req/min)

If you exceed these limits, you will receive a 429 (Too Many Requests) response. Please implement appropriate caching and retry logic in your applications.

Response Codes

200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid parameters or validation error
401Unauthorized - Authentication required or invalid
403Forbidden - Insufficient permissions
404Not Found - Resource does not exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong

API Status & Support

Total Endpoints: 50+ endpoints across all categories

Public Endpoints: 3 (no authentication required)

Authenticated Endpoints: 35+ (requires session or API key)

Admin Endpoints: 9 (admin access required)

For issues, feature requests, or API support, please contact us through the contact form or visit our Discord community.