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: api.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 the ship catalog). 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.
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: api.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: api.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: api.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.
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.
Find Ships and Refresh Just One
Every ship route reads one cached catalog, so lookups are free. Filter it with GET /v2/ships/search — every parameter is optional and they combine with AND:
GET /v2/ships/search?type=combat,multi&manufacturer=DRAK&crew_min=2 HTTP/1.1
Host: api.starcitizen-api.com
x-api-key: YOUR_API_KEY
| Parameter | Matches |
|---|---|
name, focus | Partial text, case-insensitive |
type, manufacturer, size, production_status | Any of the listed values (type=combat,multi), case-insensitive |
length_*, beam_*, height_*, mass_*, crew_*, cargo_*, price_*, scm_speed_* | _min / _max ranges; crew_* compares against max_crew |
For a single ship, use a direct lookup instead: GET /v2/ships/{id}, GET /v2/ships/by-name/{name} (exact name), or GET /v2/ships/by-chassis/{chassisId} for every variant of a chassis. GET /v2/ships/manufacturers lists the manufacturer codes you can filter on.
When you need one ship's live data, refresh it by id (or by exact name) rather than refreshing the catalog:
GET /v2/ships/56?refresh=true HTTP/1.1
Host: api.starcitizen-api.com
x-api-key: YOUR_API_KEY
Refresh one ship for 1 daily request, not 10.
?refresh=true on GET /v2/ships/{id}, /by-name/{name} or /by-chassis/{chassisId} scrapes only those ships and updates them in the shared catalog, so every other ship route sees the new data too. The same flag on GET /v2/ships or /v2/ships/search re-scrapes the whole catalog for 10 daily requests.
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: api.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: api.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 |
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.