krisyotamAdd scripts, technical, community sections and migrate tips34599227 months agoHistory
127 lines · 4.0 KB · MarkdownRawDownload

Gaia Service Interface (GSI) API

The GSI (Game Server Interface) was Gaia Online's internal API, exposed at a semi-public endpoint. It was never officially documented for third-party developers, but the community reverse-engineered it extensively from ~2008 onward. Multiple open-source libraries and userscripts were built on top of it.

Base URL

https://www.gaiaonline.com/chat/gsi/json.php

An older endpoint was also used in some scripts:

http://www.gaiaonline.com/chat/gsi/index.php?v=json

The JSON endpoint is the canonical modern form. The index.php?v=json form was used in older userscripts and behaves identically.

Authentication

The GSI does not use API keys or OAuth. Some endpoints are publicly accessible without any credentials (user lookups, item lookups, aquarium data). Others require a valid Gaia session cookie.

For session-authenticated requests, the cookie gaia55_sid must be set. The Grabbit PHP library (see below) uses a placeholder session to work around this for aquarium endpoints:

'Cookie' => 'gaia55_sid=' . str_repeat('a', 48)

Whether this placeholder actually works or the endpoint just ignores the cookie for public data is not documented.

Request Format

All requests are HTTP POST (as implemented by Grabbit) or GET (as used in userscripts). The payload structure is:

m = [method_id, [arg1, arg2, ...]]
X = unix_timestamp (10-digit)

For batch requests (multiple methods in one call), m is a JSON array of pairs:

m = [[method_id_1, [args_1]], [method_id_2, [args_2]], ...]

Example URL-encoded GET (from the "Is It Glowing?" userscript):

GET /chat/gsi/index.php?v=json
  &m=[[6500,[1]],[6510,["12345",0,1]],[6511,["12345",0]]]
  &X=1694000000

Response Format

Responses are JSON arrays. Each element corresponds to one method call in the request:

[
  [method_id, success_bool, data_object],
  [method_id, success_bool, data_object],
  ...
]
  • success_bool is true on success, false on error
  • On error, data_object is typically [error_code, error_message]
  • On success, data_object shape varies by method

Known Limitations and Rate Limits

No official rate limits were published. Community experience suggests:

  • Rapid repeated polling (< 5 second intervals) could result in temporary blocks
  • The "Is It Glowing?" script polled every 30 seconds per tank, which was considered safe
  • Batch requests (multiple methods in one call) were encouraged to reduce request count

The GSI may be partially or fully down as of 2024–2025. Gaia Online's activity has declined dramatically, and there is no evidence the company actively maintains the API infrastructure.

Libraries Built on GSI

Grabbit (PHP)

  • Repo: https://github.com/GlowGaia/Grabbit
  • Install: composer require glowgaia/grabbit
  • Framework: Saloon HTTP client
  • Methods supported: 102 (users), 712 (items), 6510 (aquarium), 6511 (inhabitants)
  • Status: Active as of late 2025

glibrary (Python)

gaia-shell

JGaia (Java)

GaiaOnline.Unity.Library (C#)

Sources

Endpoint URLs recovered from: