Skip to main content
Version: Weekly Build

Public API Reference

This document outlines the REST API endpoints available for managing Organizations and their associated Teams and Members.

Interactive API Docs (Swagger UI)

You can explore and interactively test all available API endpoints directly on your Codesphere instance by navigating to: https://[your_instance_URL]/api/swagger-ui/

Cluster Administration​

The following endpoints operate at the cluster level and are intended for platform operators. Unlike the organization endpoints below (which are scoped to the organizations you belong to), these give a cluster-wide view and allow you to provision new organizations and administrators.

Requirements

To use these endpoints, the following must be in place:

  • cluster-admin flag enabled — The endpoints are gated behind the cluster-admin flag and are only registered when it is enabled; otherwise requests return 404 Not Found. Cluster admin authorization is backed by OpenFGA, so the openfga-authz preview flag must be enabled alongside it (the team service fails to start otherwise). Enable both flags in your config.yaml:

    codesphere:
      experiments:
        - cluster-admin
      preview:
        openfga-authz: true

    See Feature Flags for more on configuring flags.

  • Cluster admin privileges — The authenticated user must be a cluster admin; requests from other users are rejected with a NotAuthorized error. You become a cluster admin either by getting assigned during the installation of the cluster, or by getting promoted by an existing cluster admin via the Add Cluster Admin endpoint.

List All Organizations​

Retrieves every organization in the cluster, newest first. This differs from List Organizations, which only returns the organizations the authenticated user is a member of.

  • URL: GET /clusters/organizations
  • Parameters: None.

Create Organization​

Creates a new organization together with its initial admin. If the provided admin email does not yet have a Codesphere account, a pending (unregistered) user is created for that email. Once a user registers with that email address, they automatically become an admin of the organization.

  • URL: POST /clusters/organizations
  • Parameters:
    • Body:
      • name (String): The name of the new organization.
      • adminEmail (String): The email address of the user to assign as the organization's initial admin.
  • Errors:
    • InvalidArgument - Returned if an existing account for adminEmail is deactivated.

Add Cluster Admin​

Grants a user cluster admin privileges. If the provided email does not yet have a Codesphere account, a pending (unregistered) user is created.

  • URL: POST /clusters/admins
  • Parameters:
    • Body:
      • email (String): The email address of the user to grant cluster admin privileges.
  • Errors:
    • InvalidArgument - Returned if an existing account for email is deactivated.

Organization Management​

List Organizations​

Retrieves a list of all organizations the authenticated user is a member of.

  • URL: GET /organizations
  • Parameters: None.

List Organization Teams​

Retrieves all teams that are officially grouped under a specific organization.

  • URL: GET /organizations/{organizationId}/teams
  • Parameters:
    • Path:
      • organizationId (UUID) - The unique identifier of the organization.

Member Management​

List Organization Members​

Retrieves a list of all users that are part of the specified organization, including their current roles and status.

  • URL: GET /organizations/{organizationId}/members
  • Parameters:
    • Path:
      • organizationId (UUID) - The unique identifier of the organization.

Add Organization Member​

Adds an existing user to an organization. Note that adding a user to an organization is a prerequisite before they can be added to any team within that organization.

  • URL: POST /organizations/{organizationId}/members
  • Parameters:
    • Path:
      • organizationId (UUID)
    • Body:
      • email (String): The valid email address of the user to add.
      • role (String): The role to assign ('admin' or 'member').

Change Organization Role​

Updates the organizational role of an existing member (e.g., promoting a member to an admin).

  • URL: PUT /organizations/{organizationId}/members/{userId}/role
  • Parameters:
    • Path:
      • organizationId (UUID)
      • userId (Number) - The userId of the member.
    • Body:
      • role (String): The new role ('admin' or 'member').

Remove Organization Member​

Removes a user from the organization.

  • URL: DELETE /organizations/{organizationId}/members/{userId}
  • Parameters:
    • Path:
    • organizationId (UUID)
    • userId (Number) - The userId of the member to remove.

Team Integration​

Create Team​

Creates a new collaborative team. Depending on the environment's standalone-teams configuration, teams may need to be strictly tied to an organization.

  • URL: POST /teams
  • Parameters:
    • Body:
      • name (String): The name of the new team.
      • dc (Integer): The Data Center ID where the team is hosted.
      • organizationId (UUID, Conditional): The ID of the organization this team belongs to.
        • Note: If the standalone-teams feature flag is disabled on your instance, this parameter is strictly required, and the requesting user must be a member of this organization.

Migrate Team to Organization​

Migrates an existing, standalone team into an organization or a team which is already part of an organization into another organization. This is primarily used to consolidate legacy teams under the new Unified Governance structure.

  • URL: POST /teams/{teamId}/migrate
  • Parameters:
    • Path:
      • teamId (Integer)
    • Body:
      • organizationId (UUID): The target organization.
      • force (Boolean, Optional): Because a team within an organization can only contain organization members, migrating a team might cause conflicts if some team members aren't part of the target organization.
        • If force: true, these non-organization users will be automatically removed from the team during migration.
        • If force: false (or omitted), the API will abort the migration and return an error (TeamMigrationFailed) if non-members are detected.