Skip to content

API Changelog

This page lists changes to RocketFlag’s public APIs. Each entry says which API it affects and whether it needs any action from you.

The Management API (/api/v1) is additive only. Within a version:

  • Fields are only ever added to responses. They are never renamed, retyped or removed.
  • New optional request fields and new endpoints may appear.
  • A change to how existing behaviour works gets a new version, served alongside the old one, instead of changing v1 under you.

Write your scripts to ignore fields they do not recognise, and they will keep working.


Released 10 November 2026.

  • Browser-authenticated user CLI sessions (rfu_...): The Management API now accepts 7-day browser-authenticated user CLI sessions (Authorization: Bearer rfu_...) alongside project API tokens (rf_...). CLI sessions work across every plan (including Free). Flag mutations made with a user CLI session attribute changes directly to the authenticated user in audit logs.
  • Project listing endpoint (GET /api/v1/projects): Lists all projects accessible to the caller. When called with a project API token (rf_...), returns the single project scoped to the token. When called with a user CLI session (rfu_...), returns all accessible personal, shared personal, and organisation projects with their ID, name, organisation details, environment labels, and effective permission (read or write).
  • Target project header for CLI sessions (X-RocketFlag-Project): When calling project-scoped endpoints (such as GET /api/v1/flags or PATCH /api/v1/flags/{id}) with a user CLI session, clients must send X-RocketFlag-Project: <projectId>. Project API tokens continue to deduce the project from the token (sending a mismatched X-RocketFlag-Project header returns 400 Bad Request).
  • Token introspection enhancements (GET /api/v1/token): The response now returns kind: "token" for project API tokens, or kind: "user" for user CLI sessions. For user sessions, it includes user identity (id, email, name), device name, and expiry, along with target project details and effective permission when X-RocketFlag-Project is provided.
  • Session revocation endpoint (POST /api/v1/session/revoke): Revokes the calling user CLI session (204 No Content). Calling this endpoint with a project API token returns 400 Bad Request.

Released 8 November 2026.

  • Hosted Streamable HTTP MCP endpoint (POST /mcp/v1): RocketFlag now serves a stateless Model Context Protocol (MCP) endpoint on the management plane at https://api.rocketflag.app/mcp/v1, authenticated with project API tokens (Authorization: Bearer rf_...). It exposes six management-plane tools (whoami, list_flags, get_flag, create_flag, update_flag, and toggle_flag) for AI coding assistants such as Claude Code, Cursor, and Antigravity without requiring a local Node.js or npx installation. Cross-origin preflight responses on /mcp/v1 also include Mcp-Session-Id and Mcp-Protocol-Version in Access-Control-Allow-Headers. See the CLI & MCP Server reference.

Released 6 November 2026.

  • Project environments on token introspection: GET /api/v1/token now includes project.environments (string[]), returning the project’s configured environment labels on multi-environment projects or [] on single-environment projects. This sits alongside top-level environments, which lists the token’s own environment restrictions (or [] when unrestricted), allowing clients such as the RocketFlag CLI and MCP Server to distinguish single-environment and multi-environment projects in a single call.
  • Immediate token revocation on project or organisation deletion: Deleting a project or organisation now immediately revokes all associated API tokens and purges their denial history. Requests using a token from a deleted project or organisation immediately receive 401 Unauthorized (Token revoked).
  • Client telemetry CORS header: Cross-origin preflight responses on /api/v1 now include X-RocketFlag-Client in Access-Control-Allow-Headers alongside Authorization and Content-Type.

Released 22 October 2026.

  • Environment-scoped token filtering: When listing flags (GET /api/v1/flags), getting a flag without ?env= (GET /api/v1/flags/{id}), or creating a flag (POST /api/v1/flags) using a token restricted to specific environments, the environments map on each group flag is now filtered to only include the environments within the token’s allowed scope.
  • Environment enforcement on flag get: GET /api/v1/flags/{id}?env={env} now enforces token environment restrictions and returns 403 Forbidden (Environment not permitted) when the requested environment is outside the token’s scope.

Released 1 October 2026, together with evaluation release eval-v1.1.0.

The Management API is available on the Teams and Enterprise plans. See the Management API reference. API tokens and audiences are a Preview first iteration and may change.

  • GET /api/v1/token describes the calling token: project, permission, environments and expiry.
  • GET /api/v1/flags lists flags, with an exact-match ?name= filter.
  • GET /api/v1/flags/{id} returns one flag. ?env= projects a group flag to a single environment.
  • POST /api/v1/flags creates a flag, flat on single-environment projects and with environments on multi-environment ones.
  • PATCH /api/v1/flags/{id} changes a flag with merge patch semantics: present keys replace, absent keys are untouched, cohorts: [] clears, audienceId: null detaches an audience. A patch that changes nothing returns "changed": false and writes nothing.
  • Authentication is a bearer token (rf_...) created in the console, with read or write permission and an optional environment restriction.
  • Every error uses one envelope, {error, detail, docs}, and the docs link points at the section of the reference that explains it.
  • audienceId is present on every flat flag representation, and on each entry of environments. It is null when the flag has no audience.

The additions below to GET /v1/flags/{flag_id} and GET /v1/flags/project/{project_id} need no action, but three behaviours change, and they come first.

  • Behaviour change: an invalid cohort on the project route is a 400. GET /v1/flags/project/{project_id} with a cohort that cannot be decoded now returns 400 Bad Request, the same as the single-flag route. It used to return 200 with an empty list, which was indistinguishable from a project with no flags. If your code treats an empty list from this route as “no flags”, check that it also handles a 400. Requests with a valid or absent cohort are unaffected.

  • Behaviour change: cohort matches are always on. A request whose cohort matches the flag’s cohorts now evaluates to true regardless of the traffic percentage. Previously a matching cohort still had to pass the percentage, so a cohort-gated flag below 100% was off for some matching cohort members. Flags with no cohorts, or with cohorts at 100%, behave as before.

  • Behaviour change: sticky percentage rollouts. Send targetingKey (a stable id such as a user id) and a flag below 100% gives that key the same answer on every request, instead of a fresh random draw each time. If you send only cohort, the cohort is used as the bucketing key, so those requests are now sticky too. A request that carries neither key is still a random roll on every request, as it always was.

  • Attributes. Any other query parameter is passed to the flag as an attribute for audience matching, for example ?plan=pro&country=AU. targetingKey, cohort and env keep their own meanings and are not treated as attributes.

  • Audiences. A flag can now use a project audience, a named set of attribute rules, in addition to cohorts. Audiences are exact-match rules. There is no regex, no version comparison and no numeric comparison. Audiences are available on the Teams and Enterprise plans.

The SDKs pass targetingKey and attributes through their existing context objects, so there are no signature changes. In TypeScript, cast the context to UserContext until the next Node and React SDK release widens the type (see the SDK pages).