# 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:

```php
'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:

```json
[
  [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)
- **Repo:** https://github.com/0x0018/glibrary
- **Description:** "A (very) generic library for programs targeting Gaia Online"
- **Language:** Python 100%

### gaia-shell
- **Repo:** https://github.com/Protozoid/gaia-shell
- **Description:** "Shell for performing certain actions on Gaia Online dynamically"
- **Notes:** Minimal documentation; 3 commits

### JGaia (Java)
- **Repo:** https://github.com/jazzbom/JGaia
- **Description:** Java library for interacting with Gaia Online forums
- **Status:** Inactive (1 commit, 0 stars)

### GaiaOnline.Unity.Library (C#)
- **Repo:** https://github.com/GaiaOnlineCommunity/GaiaOnline.Unity.Library
- **Description:** Unity3D integration for rendering Gaia content
- **License:** AGPL-3.0

---

## Sources

Endpoint URLs recovered from:
- [GlowGaia/Grabbit source code](https://github.com/GlowGaia/Grabbit) (GSIRequest.php, GaiaConnector.php)
- [is-it-glowing.user.js](../userscripts/is-it-glowing.user.js) (batch request URL construction)
- [mail-checker.user.js](../userscripts/mail-checker.user.js) (method 102 usage)