Common Patterns

Ready-to-use recipes for the most common API use cases. Each recipe is self-contained.

---

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": YOUR_DAILY_REQUEST_LIMIT,
    "role": "user"
  }
}

`dailyRequestsRemaining` decreases by one for each `?refresh=true` request. 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. Call `GET /managements/status` (no API key needed) for the exact next-reset timestamp — see [Rate Limits & Quota](../concepts/rate-limits#quota-reset-schedule).

---

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

<ApiKeyCodeBlock language="http">{`GET /v2/users/dymerz HTTP/1.1
Host: API_HOST
x-api-key: YOUR_API_KEY`}</ApiKeyCodeBlock>

```json
{
  "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

---

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

---

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. The smart cache will serve fresh data automatically when a new version is detected.

---

Poll Funding Stats Without Burning Quota

Combine the smart cache with ETags so you only download data when it actually changes.

First request — no ETag yet, 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 managing freshness automatically. Layering ETags on top means you skip the download entirely when nothing has changed. See HTTP Caching (ETags) for the full ETag reference.