Make Your First Request

You have a key — let's make a call. Every request needs the same three things, then you check one field in the response.

---

What Every Request Needs

Part	Value	Notes
Base URL	https://apiv2.starcitizen-api.com	Prefix every endpoint path with it, e.g. GET /v2/users/{handle}
x-api-key header	Your API key	Required on every request. A missing or invalid key returns 401
success field	true or false	Present in every JSON response — tells you whether the call worked

danger

Keep your key server-side.

Never ship it in browser code, mobile apps, or public repositories — anyone who has it can spend your quota.

---

Send the Request

Here's a request that fetches a citizen's profile:

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": []
    }
  }
}

The response is trimmed for readability. This request uses the smart cache by default, so it consumes no quota. The updatedAt field tells you when the data was last scraped from the RSI website, and expiresAt tells you when it expires: the first request after that re-scrapes it automatically, still for free. Only ?refresh=true costs daily requests.

---

Understanding the Response

Every response uses the same JSON envelope, whether it succeeds or fails.

Success:

Field	Type	Description
success	boolean	Always true
message	string	Human-readable status
updatedAt	string	When the data was last scraped from RSI (ISO 8601). Omitted when not available
expiresAt	string	When the cache expires and the next request re-scrapes it (ISO 8601). Omitted when not available
data	any	The response payload

Error:

{
  "success": false,
  "message": "Invalid API key",
  "code": 401
}

Field	Type	Description
success	boolean	Always false
message	string	Human-readable error description
code	number	HTTP status code

warning

Check the HTTP status code and success before reading data.

A failed request returns a non-2xx status (401, 404, 429, ...), success: false, and no data field — code that reads data without checking first will crash or silently use undefined. Branch on the status code or success, never on message: its wording may change without notice.

For the full response format reference, see Response Format.

---

Next Steps

You're making requests — here's where to go next:

• Response Format — full envelope reference, including what updatedAt/expiresAt mean
• Data Freshness & Caching — when to use ?refresh=true and how the smart cache works
• API Reference — every endpoint with parameters and response schemas
• Common Patterns — ready-to-use recipes for quota checking, org lookups, version polling, and more