API Documentation - Create Mod Servers

Authentication

All API requests require a valid API key sent via the Authorization header.

Authorization: Bearer cms_your_api_key_here

To create an API key:

Go to your Profile page
Scroll to the API Keys section
Enter a name and click Create Key
Copy the key immediately, because it is only shown once

Keep your API key secret. Do not share it in public repositories, client-side code, or chat messages. If compromised, delete the key from your profile and create a new one.

Rate Limits

API requests are rate-limited to 60 requests per minute per API key. Statistics data is updated every 5 minutes, so polling more frequently than that will return the same data.

Endpoints

GET /api/v1/servers/{id}/stats

Returns detailed statistics and analytics for a server you own. The {id} is the short ID visible in your server's URL (e.g. a1b2c3d4 from /server/a1b2c3d4).

Example Request

curl -H "Authorization: Bearer cms_your_api_key_here" \
  https://www.createmodservers.com/api/v1/servers/a1b2c3d4/stats

Example Response

{
  "server": {
    "id": "a1b2c3d4",
    "name": "My Create Server",
    "status": "approved",
    "is_online": true,
    "players_online": 12,
    "max_players": 50,
    "votes": 142
  },
  "analytics": {
    "views_today": 45,
    "views_week": 312,
    "views_month": 1205,
    "views_all_time": 8432,
    "daily_views": [{"date": "2026-04-01", "count": 38}],
    "peak_players_24h": 18,
    "avg_players_24h": 8.5,
    "uptime_24h": 99.2,
    "uptime_7d": 98.5,
    "uptime_30d": 97.8,
    "votes_today": 5,
    "votes_week": 28,
    "votes_month": 89,
    "time_p50": 45000,
    "time_p90": 120000,
    "total_sessions": 890
  }
}

Response Fields

Field	Type	Description
server.is_online	boolean	Whether the server responded to the last ping
server.players_online	integer	Current player count from last ping
analytics.views_*	integer	Unique page views (deduplicated by IP per day)
analytics.peak_players_*	integer	Highest player count in 24h / 7d / 30d
analytics.avg_players_*	float	Average player count in 24h / 7d / 30d
analytics.uptime_*	float	Uptime percentage (0-100) in 24h / 7d / 30d
analytics.daily_views	array	30-day daily view counts
analytics.player_history	array	7-day hourly peak player counts
analytics.daily_uptime	array	30-day daily uptime percentages
analytics.votes_*	integer	Vote counts for today / 7d / 30d
analytics.click_counts	array	Click counts per UI element (30 days)
analytics.time_p50 / p90	float	Median and 90th percentile time-on-page (ms)

GET /api/v1/servers/{id}/votes

Returns paginated vote history for a server you own, with optional filters. Vote records are retained for 30 days; older votes are automatically removed.

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Results per page, 1-100 (default: 50)
username	string	Filter by Minecraft username (exact match)
after	string	Only votes on or after this date (`2026-04-01` or `2026-04-01T00:00:00Z`)
before	string	Only votes on or before this date/time

Example Request

curl -H "Authorization: Bearer cms_your_api_key_here" \
  "https://www.createmodservers.com/api/v1/servers/a1b2c3d4/votes?username=Steve&after=2026-04-01&page=1"

Example Response

{
  "votes": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "server_id": "660e8400-e29b-41d4-a716-446655440001",
      "mc_username": "Steve",
      "created_at": "2026-04-15T14:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "server_id": "660e8400-e29b-41d4-a716-446655440001",
      "mc_username": "Steve",
      "created_at": "2026-04-14T09:15:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 50,
  "total_pages": 1
}

Error Responses

Errors return a JSON object with an error field.

Status	Meaning
401 Unauthorized	Missing or invalid API key
403 Forbidden	You do not own the requested server
404 Not Found	Server ID does not exist
500 Internal Server Error	Unexpected server error, try again later

{"error": "You do not own this server"}