API Overview

Overview of the modl Developer API including authentication, base URL, and response format.

Base URL

All API requests are made to the following base URL:

https://api.modl.gg/v1/minecraft

Authentication

All requests require the X-API-Key header with your server's API key. You can obtain your API key from your server's panel settings.

X-API-Key: your-api-key-here

Multi-Tenancy

Requests are automatically scoped to the server associated with your API key. You do not need to specify a server ID or domain in your requests.

Response Format

All responses are returned as JSON with appropriate HTTP status codes.

Common Error Codes

Status Code	Description
`400`	Bad Request -- Your request is malformed or missing required fields.
`401`	Unauthorized -- Missing or invalid API key.
`403`	Forbidden -- Insufficient permissions for this action.
`404`	Not Found -- The requested resource does not exist.
`409`	Conflict -- The request conflicts with the current state of the resource.
`413`	Payload Too Large -- The request body exceeds the maximum allowed size.
`429`	Rate Limited -- You have exceeded the rate limit. Slow down and retry after the indicated time.
`500`	Internal Server Error -- Something went wrong on our end. Try again later.

Rate Limiting

API requests are subject to rate limiting. If you receive a 429 response, wait before retrying. Rate limit details are included in the response headers.