Ravensight

Manage your studio from an agent

The Organization API uses your existing RealitySE account, Ravensight studio and membership. Use a whole-studio programmatic token with /api/v1/data/org, or the matching MCP tools. Every operation costs one programmatic call, 100,000 weighted events. Project-restricted tokens cannot use this surface. Reads return at most 500 rows and a truncated flag.

Endpoints and tools

REST under /api/v1/data/orgMCPRole permission
GET /games, /projects, /membersorg_list_games, org_list_projects, org_list_membersorg:read
GET /invitesorg_list_invitesorg:manage_members
POST /games, /projectsorg_create_game, org_create_projectgame:create
PATCH /games/{gameId}org_update_gamegame:write
POST /invitesorg_create_inviteorg:manage_members
DELETE /members/{userId}, /invites/{inviteId}org_remove_member, org_revoke_inviteorg:manage_members
GET /games/{gameId}/key-recommendationorg_recommend_keyorg:read
POST /games/{gameId}/keysorg_issue_keykey:rotate
DELETE /games/{gameId}/public-keys/{keyPrefix}org_revoke_public_keykey:rotate

Writing

Writes require canManage. The owner enables Allow organization management on the token in Settings. This is separate from Allow writes for studio context. The token holder must also have the permission above: an admin can create games, but only an owner manages invitations and members. Money and tokens cannot be managed through these operations, and ingest keys need the separate permission described under Give an agent a key. Games and projects cannot be deleted; yourself and the owner cannot be removed.

Create a project with { "name": "Next game", "engine": "godot" }. Create a game with gameId, name, optional projectId, engine and environment. Without a projectId, a title is created automatically. The initial ingest key is never returned to the agent; issue one to a file or rotate it in Settings to connect the game. Game updates accept only name and environment, and a game whose key has been used cannot be moved here from a public environment to an internal one, and a used production game keeps its environment (409 environment_locked).

Invite with { "email": "teammate@example.com", "role": "member" } (member, admin or viewer; a viewer can read the studio but not change it or ask Huginn). This creates the usual seven-day invitation and sends the standard email; acceptance requires that verified RealitySE address. Member removal also revokes that member’s studio CLI credentials. Incoming analytics shares do not grant organization access, and foreign resource IDs return 404.

REST writes require X-Ravensight-Operation-Id, 8 to 100 letters, digits, dots, colons, underscores or hyphens. Retry identical input with the same ID to reuse the stored result without another mutation, invitation or charge. Unknown fields are rejected. Audit rows record counts and resource IDs, never submitted names or invitation addresses. OpenAPI specification.

Give an agent a key

An agent that sets up a game also needs its ingest key, and a key pasted into a conversation is a leaked key. So no tool ever answers a key. org_issue_key answers a single-use claim, and the claim is exchanged once for a file, .env.ravensight, that the agent's own shell writes.

The owner turns it on. In Settings, on the token, switch on Allow agents to issue ingest keys. It needs Allow organization management as well, it is off for every token until an owner turns it on, and the token holder still needs a role that may rotate keys (owner or admin). A token restricted to a project cannot have it turned on, and a connected app that signed in through the consent screen cannot issue keys (403 key_management_unavailable).

  1. Ask which key fits. org_recommend_key takes the game and how the build reaches people, and answers the kind of key, the reason, whether a separate environment is advised, whether the key can be issued now, and the steps. The rule is fixed and uses no model: it is the one in Public builds.
  2. Issue the claim. Call org_issue_key with { "kind": "live" }, or with { "kind": "public", "policy": { "allowed_events": ["game_started", "level_up"] } }. The answer has no key in it. It carries a claim that works once, for 10 minutes, and a command.
  3. Check the ignore file. Confirm .env.ravensight is ignored by version control before anything else.
  4. Run the command. The key is created at that moment and written to the file. It is not shown anywhere else.

The command the claim answers

printf 'X-Ravensight-Claim: %s' '<code>' | curl -fsS -X POST -H @- \
  https://api.ravensight.io/api/v1/data/org/key-claims/redeem -o .env.ravensight

The header is piped in, so the code is never an argument of curl. A tool that runs the whole command as one sh -c string still shows it as that shell's argument for the moment it runs, which is one reason the code works once and for 10 minutes only. The URL is always the API host itself. Without a POSIX shell or curl 7.55, send the same request with any HTTP client: claim.url, the X-Ravensight-Claim header set to claim.code, and the body saved as the file.

.env.ravensight, as written

# Ravensight, My next game (development), live key, prefix gt_live_Ab12Cd34
# Keep this file out of version control.
RAVENSIGHT_INGEST_KEY=gt_live_xxxx
RAVENSIGHT_KEY=gt_live_xxxx
RAVENSIGHT_API_URL=https://api.ravensight.io
RAVENSIGHT_GAME_ID=my-next-game-dev
RAVENSIGHT_ENVIRONMENT=development
DistributionKeyEnvironment it suggests
private_testersLivebeta, alpha, early-access or staging
internal_ciLivedevelopment or staging
store_releaseLiveproduction or early-access
public_demoPublicdemo
web_buildPublicThe game's own
open_sourcePublicThe game's own
  • A public key needs its allowlist. A new game has no traffic to suggest event names from, and a key with an empty allowlist refuses every event while still holding a place. Send policy.allowed_events with at least one of the names the game sends, read from its code, or the call answers 400 allowed_events_required. label, expiresAt and the rest of the policy are optional. At two live public keys the call answers 409 public_key_limit; org_revoke_public_key frees a place by the key's prefix.
  • A live key replaces the old one. For a game whose key has already been used, every build using the old key stops reporting at once. In the four internal environments, development, staging, alpha and beta, the call needs "rotate": true and answers 409 rotate_required without it. There, a game whose key has never been used needs no flag. In every other environment a key that has never been used also needs "rotate": true: a build already shipped with it and not yet reporting, such as one waiting in store review, stops reporting when the key is replaced, and nothing on the server can see that build, so confirm with the studio first. A key counts as used once any build has authenticated with it: an event, a remote config read, a player account call, a session, or a request refused after the key was recognised.
  • A build the public plays stays in the dashboard. In production, early-access, demo and any environment you named yourself, the live key of a game whose key has been used is rotated in Settings only, and so is revoking one of its public keys. Both answer 409 key_dashboard_only, with or without rotate. An agent cannot move such a game to an internal environment either, or change the environment of a used production game at all (409 environment_locked).
  • The claim is the credential. POST /api/v1/data/org/key-claims/redeem takes no token, only the code in the X-Ravensight-Claim header, never in a URL. It checks again that the token that issued the claim is live and still has both permissions, and that its holder still has the role. An unknown, used or expired code answers 404 claim_not_found, the same answer in every case. A valid code can still answer 409 with rotate_required, key_dashboard_only, public_key_limit, invalid_expires_at or steam_connection_missing when things changed after the claim was issued, and the claim is kept for another try. If creating the key fails part way the answer is 500 claim_spent: issue a new claim. It allows 5 tries per claim from one address and 20 per address in 10 minutes, then answers 429 rate_limited.
  • What it costs. Each of the three tools is one programmatic call, 100,000 weighted events on the shared event meter, like every other organization operation. Redeeming the claim has no charge of its own.
  • Retries. Repeating org_issue_key with the same operation ID answers the same claim and cannot create a second key. A lost redemption answer is not retried: issue a new claim. A lost public key still holds one of the two places until you revoke it.
  • What the file is not. It keeps the key out of the conversation by default. It is not a security boundary: an agent that can read the disk can read the file. An engine that does not read environment variables, such as a Godot script with an exported ingest_key, still needs the key placed in the project or the build step, which is expected for a key that ships inside a build.
  • The trail. Your audit log records the issue with the key's kind, and the redemption and a revoke with the kind and the prefix. A redeemed live key also appears as a key rotation, and a public key as created or revoked, the same entries the dashboard writes. The key, the claim code and the policy are never written to it.