Cookbook

Ready-to-use recipes for common API patterns.

---

Check Your Remaining Quota

Call GET /v2/me to retrieve quota information programmatically without visiting the dashboard.

GET /v2/me HTTP/1.1
Host: API_HOST
x-api-key: YOUR_API_KEY

{
  "success": true,
  "message": "ok",
  "data": {
    "key": "YOUR_API_KEY",
    "provider": "Discord",
    "dailyRequestsRemaining": 847,
    "dailyRequestLimit": 1000,
    "role": "user"
  }
}

dailyRequestsRemaining decreases by one for each request that uses ?refresh=true. Requests without it never count toward the quota.

tip

Build quota awareness into your app: check dailyRequestsRemaining at startup. Use ?refresh=true only when you genuinely need real-time data; for everything else, the smart cache handles freshness automatically.

Time until next reset

Your daily quota resets at a fixed time each day. Check GET /managements/status (no API key needed) for the exact next-reset time, or see Data Freshness for details.

---

Look Up a Citizen and Their Org in One Call

GET /v2/users/:handle returns both the user profile and their primary organization in a single response.

GET /v2/users/dymerz HTTP/1.1
Host: API_HOST
x-api-key: YOUR_API_KEY

{
  "success": true,
  "message": "ok",
  "updatedAt": "2026-05-31T10:00:00.000Z",
  "data": {
    "profile": {
      "handle": "Dymerz",
      "display": "[ΩP] Dymerz",
      "enlisted": "2016-08-19T00:00:00.000000",
      "fluency": ["French", "English"]
    },
    "organization": {
      "name": "Protectorat (EU/QC/974/PC)",
      "sid": "PROTECTORA",
      "rank": "Membre"
    }
  }
}

If you only need one of the two, use the sub-routes to reduce payload size:

Need only…	Use
Profile only	GET /v2/users/:handle/profile
Org only	GET /v2/users/:handle/organization

---

Get the Latest Game Version

Use ?filter=latest to retrieve only the most recent patch note instead of the full list.

GET /v2/versions?filter=latest HTTP/1.1
Host: API_HOST
x-api-key: YOUR_API_KEY

You can also look up a specific version with ?version=X.Y.Z:

GET /v2/versions?version=4.0.1 HTTP/1.1
Host: API_HOST
x-api-key: YOUR_API_KEY

tip

Skip ?refresh=true for version lookups — patch notes only change when a new update ships, so a force-refresh is rarely worth the quota cost.

---

Poll Funding Stats Without Burning Quota

Combine auto mode with ETags so you only pay quota when the data actually changes.

First request — no ETag yet, just send normally:

GET /v2/stats?chart=day HTTP/1.1
Host: API_HOST
x-api-key: YOUR_API_KEY

Save the ETag value from the response header. On every subsequent request, send it back:

GET /v2/stats?chart=day HTTP/1.1
Host: API_HOST
x-api-key: YOUR_API_KEY
If-None-Match: "a1b2c3d4e5f6"

Response	What it means
200 OK	Data changed — read the new body and store the new ETag
304 Not Modified	Nothing changed — use your cached copy, no body to parse

note

The smart cache already avoids unnecessary live fetches by auto-managing freshness. Layering ETags on top means you skip the download entirely when the cached data hasn't changed. See Advanced Features for the full ETag reference.

---

Search Org Members

Use GET /v2/organizations/searchMembers to filter members of an organization by handle, rank, role, or main-org status.

GET /v2/organizations/searchMembers?sid=PROTECTORA&search=dym&page=1&pageSize=10 HTTP/1.1
Host: API_HOST
x-api-key: YOUR_API_KEY

Parameter	Required	Description
sid	Yes	Organization SID (e.g. PROTECTORA)
search	No	Filter by handle or display name
rankIndex	No	Filter by rank name
roleIndex	No	Filter by role index
isMainOrg	No	true to include only members for whom this is their main org
page	No	Page number (default: 1)
pageSize	No	Results per page, 1–100