Common Patterns

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

---

Check Your Daily Limit

Call GET /v2/me to retrieve your API key, daily limit and remaining requests without visiting the dashboard.

GET /v2/me HTTP/1.1
Host: apiv2.starcitizen-api.com
x-api-key: YOUR_API_KEY

{

  "success": true,

  "message": "ok",

  "data": {

    "_id": "665f1c2e8b1e4a0012ab34cd",

    "provider": "Discord",

    "key": "YOUR_API_KEY",

    "dailyRequestLimit": 500,

    "dailyRequestsRemaining": 500,

    "createdAt": "2025-05-18T00:00:00.000Z",

    "updatedAt": "2025-05-18T00:00:00.000Z",

    "blocked": null

  }

}

The daily request limit only applies to ?refresh=true requests (1 each, 10 for GET /v2/ships). Requests without it never count toward the quota — even when they trigger an automatic re-scrape of expired data. You can also read the X-Quota-Consumed header on any response to see what that call cost.

tip

Build quota awareness into your app by reading 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 /management/status (no API key needed) for the exact next-reset timestamp — see Rate Limits & Quota.

---

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: apiv2.starcitizen-api.com
x-api-key: YOUR_API_KEY

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

organization.organization is the citizen's main organization; organization.affiliations lists the others. The response is trimmed for readability.

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/{sid}/members to filter members of an organization by handle, rank, role, or main-org status.

GET /v2/organizations/PROTECTORA/members?search=dym&page=1&pageSize=10 HTTP/1.1
Host: apiv2.starcitizen-api.com
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 member rank (string)
roleIndex	No	Filter by role index (integer)
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 (default: 10)

---

Get the Latest Game Version

GET /v2/versions returns the most recent patch note in data.latest (or null if none) and the full list, newest first, in data.versions.

GET /v2/versions HTTP/1.1
Host: apiv2.starcitizen-api.com
x-api-key: YOUR_API_KEY

{
  "success": true,
  "message": "ok",
  "data": {
    "latest": { "title": "Star Citizen Alpha 4.10.1", "version": "4.10.1", ... },
    "versions": [ { "title": "Star Citizen Alpha 4.10.1", "version": "4.10.1", ... }, ... ]
  }
}

To look up a specific version, find it in data.versions on the client.

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. Versions have the shortest refresh interval of all endpoints, so the smart cache picks up a new release quickly on its own.

---

Poll Funding Goals 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/funding-goals?chart=day HTTP/1.1
Host: apiv2.starcitizen-api.com
x-api-key: YOUR_API_KEY

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

GET /v2/funding-goals?chart=day HTTP/1.1
Host: apiv2.starcitizen-api.com
x-api-key: YOUR_API_KEY
If-None-Match: W/"a1b2c3d4e5f60718"

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.