Developer API · v1

Citizen ID API

Confirm that a Discord user controls a given RSI handle — without scraping RSI yourself. The API only ever returns data citizens have chosen to make public.

Base URL: https://starbotid.space/api/v1

Authentication

Create a key on the developers page, then send it as a Bearer token:

Authorization: Bearer cid_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are shown once at creation — store them securely. Use keys server-side only; a key embedded in browser JavaScript is exposed to your visitors. Revoke a key anytime from the developers page.

Endpoints

Forward lookup — by RSI handle

GET /api/v1/citizens/{handle}

Reverse lookup — by Discord ID

GET /api/v1/citizens/discord/{discord_id}

Reverse lookup is the common case: a user logs into your site with Discord, you pass their Discord ID, and you get back their verified RSI handle. Reverse lookup only works if the citizen has Show Discord link enabled.

Response

{
  "handle": "SomeCitizen",
  "display_name": "Some Citizen",
  "verified": true,
  "verified_at": "2026-05-01T12:00:00.000Z",
  "avatar_url": "https://...",
  "citizen_id": "n/123456",
  "enlisted": "2014-01-01",
  "discord": { "id": "1234567890", "username": "somecitizen" },
  "organizations": [ { "name": "Example Org", "rank": "Member", "is_main": true } ],
  "location": "Stanton",
  "bio": "..."
}

Fields the citizen hasn't published are omitted from the object (not set to null).

Status codes

Code	Meaning
`200`	Found — body is the public profile.
`401`	Missing, malformed, or invalid/revoked API key.
`404`	No public+verified citizen for that handle/ID (private and nonexistent are indistinguishable by design).
`429`	Rate limited — 60 requests/minute per key. Honor the `Retry-After` header.

Example

curl -H "Authorization: Bearer cid_..." \
  https://starbotid.space/api/v1/citizens/discord/1234567890