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/

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.