Skip to main content

​
REST API

The REST API provides a language-agnostic HTTP interface to the Agones SDK, allowing integration from any language or tool that can make HTTP requests.

​
Base URL

The SDK server exposes an HTTP gateway on port 9358 by default: 
http://localhost:9358
This port is configured via the AGONES_SDK_HTTP_PORT environment variable.

​
Authentication

No authentication is required. The SDK server only listens on localhost.

​
Endpoints

​
Mark Ready

POST /ready
Marks the game server as ready to accept player connections. Example:
curl
curl -X POST http://localhost:9358/ready
Python
import requests
response = requests.post('http://localhost:9358/ready')
print(response.status_code)

​
Health Check

POST /health
Sends a health ping to indicate the server is healthy. Example:
curl
curl -X POST http://localhost:9358/health

​
Shutdown

POST /shutdown
Gracefully shuts down the game server. Example: 
curl -X POST http://localhost:9358/shutdown

​
Allocate

POST /allocate
Self-allocates the game server for a game session. Example: 
curl -X POST http://localhost:9358/allocate

​
Reserve

POST /reserve
Content-Type: application/json

{
  "seconds": 30
}
Reserves the game server for the specified number of seconds. Example: 
curl -X POST http://localhost:9358/reserve \
  -H "Content-Type: application/json" \
  -d '{"seconds": 30}'

​
Get GameServer

GET /gameserver
Retrieves the current GameServer state. Example: 
curl http://localhost:9358/gameserver
Response: 
{
  "object_meta": {
    "name": "simple-game-server-7r8nx",
    "namespace": "default",
    "uid": "...",
    "creation_timestamp": "..."
  },
  "status": {
    "state": "Ready",
    "address": "192.168.1.10",
    "ports": [
      {
        "name": "default",
        "port": 7654
      }
    ]
  }
}

​
Watch GameServer

GET /watch/gameserver
Opens a streaming connection that sends GameServer updates. Example: 
curl http://localhost:9358/watch/gameserver
This endpoint returns a stream of newline-delimited JSON objects.

​
Set Label

PUT /metadata/label
Content-Type: application/json

{
  "key": "my-label",
  "value": "my-value"
}
Example: 
curl -X PUT http://localhost:9358/metadata/label \
  -H "Content-Type: application/json" \
  -d '{"key": "map", "value": "desert"}'

​
Set Annotation

PUT /metadata/annotation
Content-Type: application/json

{
  "key": "my-annotation",
  "value": "my-value"
}
Example: 
curl -X PUT http://localhost:9358/metadata/annotation \
  -H "Content-Type: application/json" \
  -d '{"key": "version", "value": "1.2.3"}'

​
Alpha Endpoints

​
Player Connect

POST /alpha/player/connect
Content-Type: application/json

{
  "playerID": "player-123"
}

​
Player Disconnect

POST /alpha/player/disconnect
Content-Type: application/json

{
  "playerID": "player-123"
}

​
Is Player Connected

GET /alpha/player/connected/{playerID}

​
Get Connected Players

GET /alpha/player/connected

​
Get Player Count

GET /alpha/player/count

​
Get Player Capacity

GET /alpha/player/capacity

​
Set Player Capacity

PUT /alpha/player/capacity
Content-Type: application/json

{
  "count": 100
}

​
Beta Endpoints

​
Get Counter

GET /beta/counters/{key}

​
Update Counter

PUT /beta/counters/{key}
Content-Type: application/json

{
  "count": 5,
  "capacity": 10
}

​
Get List

GET /beta/lists/{key}

​
Update List

PUT /beta/lists/{key}
Content-Type: application/json

{
  "values": ["item1", "item2"],
  "capacity": 100
}

​
Add List Value

POST /beta/lists/{key}/values
Content-Type: application/json

{
  "value": "new-item"
}

​
Remove List Value

DELETE /beta/lists/{key}/values/{value}

​
Complete Example (Python)

server.py
import requests
import time
import threading

SDK_URL = 'http://localhost:9358'

def health_check():
    """Send health checks every 2 seconds"""
    while True:
        try:
            requests.post(f'{SDK_URL}/health')
        except Exception as e:
            print(f'Health check failed: {e}')
        time.sleep(2)

def main():
    # Mark as ready
    response = requests.post(f'{SDK_URL}/ready')
    print(f'Ready status: {response.status_code}')
    
    # Start health checking in background
    health_thread = threading.Thread(target=health_check, daemon=True)
    health_thread.start()
    
    # Get GameServer info
    response = requests.get(f'{SDK_URL}/gameserver')
    gameserver = response.json()
    print(f"Server name: {gameserver['object_meta']['name']}")
    print(f"Server state: {gameserver['status']['state']}")
    
    # Set a label
    requests.put(f'{SDK_URL}/metadata/label', json={
        'key': 'map',
        'value': 'desert'
    })
    
    # Run game server logic
    time.sleep(60)
    
    # Shutdown
    requests.post(f'{SDK_URL}/shutdown')

if __name__ == '__main__':
    main()

​
Error Handling

All endpoints return:
  • 200 OK - Success
  • 400 Bad Request - Invalid request body
  • 500 Internal Server Error - SDK error
Check the response status code: 
if response.status_code == 200:
    print('Success')
else:
    print(f'Error: {response.status_code}')

​
Best Practices

The REST API has higher overhead than native gRPC SDKs. Use language-specific SDKs for better performance.
The SDK server may not be available immediately. Retry with backoff.
Send health pings every 2-5 seconds, not more frequently.
Don’t parse raw HTTP responses manually - use libraries like requests (Python), axios (JavaScript), etc.

​
Next Steps

SDK Overview

Compare all available SDKs

API Reference

Complete SDK API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us