Gitpod gitpod.v1.TeamService API
TeamService manages teams and team memberships within an organization. A team is an organizational unit that users can belong to. Each user can belong to at most one team per organization.
OpenAPI Specification
openapi: 3.0.0
info:
title: gitpod.v1 gitpod.v1.AccountService gitpod.v1.TeamService API
version: v1.0.0
description: "TeamService manages teams and team memberships within an organization.\n A team is an organizational unit that users can belong to.\n Each user can belong to at most one team per organization."
servers:
- url: https://api.gitpod.io
description: Gitpod API
tags:
- description: "TeamService manages teams and team memberships within an organization.\n A team is an organizational unit that users can belong to.\n Each user can belong to at most one team per organization."
name: gitpod.v1.TeamService
x-displayName: gitpod.v1.TeamService
paths:
/gitpod.v1.TeamService/AddTeamMember:
servers: []
post:
description: "Adds a user to a team.\n\n Each user can belong to at most one team per organization.\n\n Use this method to:\n - Assign users to teams\n\n ### Examples\n\n - Add a user to a team:\n\n ```yaml\n teamId: \"d2c94c27-3b76-4a42-b88c-95a85e392c68\"\n userId: \"f53d2330-3795-4c5d-a1f3-453121af9c60\"\n ```\n\n ### Authorization\n\n Requires `teammembership:create` permission on the team."
operationId: gitpod.v1.TeamService.AddTeamMember
parameters: []
requestBody:
content:
application/json:
examples:
add_a_user_to_a_team:
description: 'teamId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
userId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
'
value:
teamId: d2c94c27-3b76-4a42-b88c-95a85e392c68
userId: f53d2330-3795-4c5d-a1f3-453121af9c60
schema:
$ref: '#/components/schemas/gitpod.v1.AddTeamMemberRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.AddTeamMemberResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: AddTeamMember
tags:
- gitpod.v1.TeamService
/gitpod.v1.TeamService/CreateTeam:
servers: []
post:
description: "Creates a new team within an organization.\n\n Use this method to:\n - Organize users into teams\n - Set up team-based workflows\n\n ### Examples\n\n - Create a team:\n\n ```yaml\n organizationId: \"b0e12f6c-4c67-429d-a4a6-d9838b5da047\"\n name: \"Backend Team\"\n ```\n\n ### Authorization\n\n Requires `team:create` permission on the organization."
operationId: gitpod.v1.TeamService.CreateTeam
parameters: []
requestBody:
content:
application/json:
examples:
create_a_team:
description: 'organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
name: "Backend Team"
'
value:
name: Backend Team
organizationId: b0e12f6c-4c67-429d-a4a6-d9838b5da047
schema:
$ref: '#/components/schemas/gitpod.v1.CreateTeamRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.CreateTeamResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: CreateTeam
tags:
- gitpod.v1.TeamService
/gitpod.v1.TeamService/DeleteTeam:
servers: []
post:
description: "Deletes a team and all its memberships.\n\n Use this method to:\n - Remove unused teams\n - Clean up after team reorganization\n\n ### Examples\n\n - Delete a team:\n\n ```yaml\n teamId: \"d2c94c27-3b76-4a42-b88c-95a85e392c68\"\n ```\n\n ### Authorization\n\n Requires `team:delete` permission on the team."
operationId: gitpod.v1.TeamService.DeleteTeam
parameters: []
requestBody:
content:
application/json:
examples:
delete_a_team:
description: 'teamId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
'
value:
teamId: d2c94c27-3b76-4a42-b88c-95a85e392c68
schema:
$ref: '#/components/schemas/gitpod.v1.DeleteTeamRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.DeleteTeamResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: DeleteTeam
tags:
- gitpod.v1.TeamService
/gitpod.v1.TeamService/GetTeam:
servers: []
post:
description: "Gets information about a specific team.\n\n Use this method to:\n - Retrieve team details and metadata\n - View member count\n\n ### Examples\n\n - Get team details:\n\n ```yaml\n teamId: \"d2c94c27-3b76-4a42-b88c-95a85e392c68\"\n ```\n\n ### Authorization\n\n Requires `team:read` permission on the team."
operationId: gitpod.v1.TeamService.GetTeam
parameters: []
requestBody:
content:
application/json:
examples:
get_team_details:
description: 'teamId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
'
value:
teamId: d2c94c27-3b76-4a42-b88c-95a85e392c68
schema:
$ref: '#/components/schemas/gitpod.v1.GetTeamRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.GetTeamResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: GetTeam
tags:
- gitpod.v1.TeamService
/gitpod.v1.TeamService/ListTeamMembers:
servers: []
post:
description: "Lists members of a team with optional pagination.\n\n Use this method to:\n - View all members of a team\n\n ### Examples\n\n - List team members:\n\n ```yaml\n teamId: \"d2c94c27-3b76-4a42-b88c-95a85e392c68\"\n pagination:\n pageSize: 20\n ```\n\n ### Authorization\n\n Requires `teammembership:read` permission on the team."
operationId: gitpod.v1.TeamService.ListTeamMembers
parameters:
- in: query
name: pageSize
schema:
default: 25
maximum: 100
minimum: 0
type: integer
- in: query
name: token
schema:
default: ''
type: string
requestBody:
content:
application/json:
examples:
list_team_members:
description: "teamId: \"d2c94c27-3b76-4a42-b88c-95a85e392c68\"\npagination:\n pageSize: 20\n"
value:
pagination:
pageSize: 20
teamId: d2c94c27-3b76-4a42-b88c-95a85e392c68
schema:
$ref: '#/components/schemas/gitpod.v1.ListTeamMembersRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.ListTeamMembersResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: ListTeamMembers
tags:
- gitpod.v1.TeamService
/gitpod.v1.TeamService/ListTeams:
servers: []
post:
description: "Lists teams with optional pagination and filtering.\n\n Use this method to:\n - View all teams in an organization\n - Search for teams by name\n\n ### Examples\n\n - List all teams:\n\n ```yaml\n pagination:\n pageSize: 20\n ```\n\n - Search for teams by name:\n\n ```yaml\n pagination:\n pageSize: 20\n filter:\n search: \"backend\"\n ```\n\n ### Authorization\n\n Results are filtered by `team:read` permission."
operationId: gitpod.v1.TeamService.ListTeams
parameters:
- in: query
name: pageSize
schema:
default: 25
maximum: 100
minimum: 0
type: integer
- in: query
name: token
schema:
default: ''
type: string
requestBody:
content:
application/json:
examples:
list_all_teams:
description: "pagination:\n pageSize: 20\n"
value:
pagination:
pageSize: 20
search_for_teams_by_name:
description: "pagination:\n pageSize: 20\nfilter:\n search: \"backend\"\n"
value:
filter:
search: backend
pagination:
pageSize: 20
schema:
$ref: '#/components/schemas/gitpod.v1.ListTeamsRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.ListTeamsResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: ListTeams
tags:
- gitpod.v1.TeamService
/gitpod.v1.TeamService/RemoveTeamMember:
servers: []
post:
description: "Removes a user from a team.\n\n Use this method to:\n - Remove users from teams\n\n ### Examples\n\n - Remove a team member:\n\n ```yaml\n teamMemberId: \"a1b2c3d4-5678-90ab-cdef-1234567890ab\"\n ```\n\n ### Authorization\n\n Requires `teammembership:delete` permission on the team."
operationId: gitpod.v1.TeamService.RemoveTeamMember
parameters: []
requestBody:
content:
application/json:
examples:
remove_a_team_member:
description: 'teamMemberId: "a1b2c3d4-5678-90ab-cdef-1234567890ab"
'
value:
teamMemberId: a1b2c3d4-5678-90ab-cdef-1234567890ab
schema:
$ref: '#/components/schemas/gitpod.v1.RemoveTeamMemberRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.RemoveTeamMemberResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: RemoveTeamMember
tags:
- gitpod.v1.TeamService
/gitpod.v1.TeamService/UpdateTeam:
servers: []
post:
description: "Updates a team's properties.\n\n Use this method to:\n - Rename a team\n\n ### Examples\n\n - Update team name:\n\n ```yaml\n teamId: \"d2c94c27-3b76-4a42-b88c-95a85e392c68\"\n name: \"Platform Team\"\n ```\n\n ### Authorization\n\n Requires `team:update` permission on the team."
operationId: gitpod.v1.TeamService.UpdateTeam
parameters: []
requestBody:
content:
application/json:
examples:
update_team_name:
description: 'teamId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
name: "Platform Team"
'
value:
name: Platform Team
teamId: d2c94c27-3b76-4a42-b88c-95a85e392c68
schema:
$ref: '#/components/schemas/gitpod.v1.UpdateTeamRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/gitpod.v1.UpdateTeamResponse'
description: Success
default:
content:
application/json:
schema:
$ref: '#/components/schemas/connect.error'
description: Error
security:
- bearerAuth: []
summary: UpdateTeam
tags:
- gitpod.v1.TeamService
components:
schemas:
gitpod.v1.AddTeamMemberRequest:
additionalProperties: false
properties:
teamId:
format: uuid
title: team_id
type: string
userId:
format: uuid
title: user_id
type: string
title: AddTeamMemberRequest
type: object
gitpod.v1.ListTeamMembersRequest:
additionalProperties: false
properties:
count:
$ref: '#/components/schemas/gitpod.v1.CountRequest'
description: count controls whether the response includes a bounded total count.
title: count
pagination:
$ref: '#/components/schemas/gitpod.v1.PaginationRequest'
title: pagination
teamId:
format: uuid
title: team_id
type: string
title: ListTeamMembersRequest
type: object
gitpod.v1.DeleteTeamRequest:
additionalProperties: false
properties:
teamId:
format: uuid
title: team_id
type: string
title: DeleteTeamRequest
type: object
connect.error:
additionalProperties: true
description: 'Error type returned by Connect: https://connectrpc.com/docs/go/errors/#http-representation'
properties:
code:
description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
enum:
- canceled
- unknown
- invalid_argument
- deadline_exceeded
- not_found
- already_exists
- permission_denied
- resource_exhausted
- failed_precondition
- aborted
- out_of_range
- unimplemented
- internal
- unavailable
- data_loss
- unauthenticated
example:
- not_found
type: string
message:
description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
type: string
title: Connect Error
type: object
gitpod.v1.AddTeamMemberResponse:
additionalProperties: false
properties:
member:
$ref: '#/components/schemas/gitpod.v1.TeamMember'
title: member
title: AddTeamMemberResponse
type: object
gitpod.v1.CountResponseRelation:
enum:
- COUNT_RESPONSE_RELATION_UNSPECIFIED
- COUNT_RESPONSE_RELATION_EQ
- COUNT_RESPONSE_RELATION_GTE
title: CountResponseRelation
type: string
gitpod.v1.ListTeamsResponse:
additionalProperties: false
properties:
pagination:
$ref: '#/components/schemas/gitpod.v1.PaginationResponse'
title: pagination
teams:
items:
$ref: '#/components/schemas/gitpod.v1.Team'
title: teams
type: array
title: ListTeamsResponse
type: object
gitpod.v1.PaginationRequest:
additionalProperties: false
properties:
pageSize:
description: "Page size is the maximum number of results to retrieve per page.\n Defaults to 25. Maximum 100."
format: int32
maximum: 100
title: page_size
type: integer
token:
description: "Token for the next set of results that was returned as next_token of a\n PaginationResponse"
title: token
type: string
title: PaginationRequest
type: object
gitpod.v1.RemoveTeamMemberResponse:
additionalProperties: false
title: RemoveTeamMemberResponse
type: object
gitpod.v1.Team:
additionalProperties: false
description: Team represents a team within an organization.
properties:
createdAt:
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: created_at
creatorId:
description: "creator_id is the ID of the user who created this team.\n May be empty for system-created or migrated teams."
format: uuid
nullable: true
title: creator_id
type: string
id:
format: uuid
title: id
type: string
memberCount:
description: member_count is the total number of members in this team.
format: int32
title: member_count
type: integer
name:
maxLength: 80
minLength: 3
title: name
type: string
organizationId:
format: uuid
title: organization_id
type: string
updatedAt:
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: updated_at
title: Team
type: object
gitpod.v1.ListTeamMembersResponse:
additionalProperties: false
properties:
count:
$ref: '#/components/schemas/gitpod.v1.CountResponse'
description: "count is the bounded total count of matching team members, present only when\n requested via CountRequest.include on the first page."
title: count
members:
items:
$ref: '#/components/schemas/gitpod.v1.TeamMember'
title: members
type: array
pagination:
$ref: '#/components/schemas/gitpod.v1.PaginationResponse'
title: pagination
title: ListTeamMembersResponse
type: object
gitpod.v1.ListTeamsRequest:
additionalProperties: false
properties:
filter:
$ref: '#/components/schemas/gitpod.v1.ListTeamsRequest.Filter'
description: filter contains options for filtering the list of teams.
title: filter
pagination:
$ref: '#/components/schemas/gitpod.v1.PaginationRequest'
title: pagination
title: ListTeamsRequest
type: object
gitpod.v1.PaginationResponse:
additionalProperties: false
properties:
nextToken:
description: "Token passed for retrieving the next set of results. Empty if there are no\n more results"
title: next_token
type: string
title: PaginationResponse
type: object
gitpod.v1.CountRequest:
additionalProperties: false
description: "CountRequest controls whether the response should include a bounded\n count of matching records."
properties:
include:
description: "When true, the first page of results will include a CountResponse with\n the bounded total. Subsequent pages (requests with a pagination token)\n will not contain the count."
title: include
type: boolean
title: CountRequest
type: object
gitpod.v1.RemoveTeamMemberRequest:
additionalProperties: false
properties:
teamMemberId:
format: uuid
title: team_member_id
type: string
title: RemoveTeamMemberRequest
type: object
gitpod.v1.UpdateTeamRequest:
additionalProperties: false
properties:
name:
maxLength: 80
minLength: 3
nullable: true
title: name
type: string
teamId:
format: uuid
title: team_id
type: string
title: UpdateTeamRequest
type: object
google.protobuf.Timestamp:
description: "A Timestamp represents a point in time independent of any time zone or local\n calendar, encoded as a count of seconds and fractions of seconds at\n nanosecond resolution. The count is relative to an epoch at UTC midnight on\n January 1, 1970, in the proleptic Gregorian calendar which extends the\n Gregorian calendar backwards to year one.\n\n All minutes are 60 seconds long. Leap seconds are \"smeared\" so that no leap\n second table is needed for interpretation, using a [24-hour linear\n smear](https://developers.google.com/time/smear).\n\n The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By\n restricting to that range, we ensure that we can convert to and from [RFC\n 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.\n\n # Examples\n\n Example 1: Compute Timestamp from POSIX `time()`.\n\n Timestamp timestamp;\n timestamp.set_seconds(time(NULL));\n timestamp.set_nanos(0);\n\n Example 2: Compute Timestamp from POSIX `gettimeofday()`.\n\n struct timeval tv;\n gettimeofday(&tv, NULL);\n\n Timestamp timestamp;\n timestamp.set_seconds(tv.tv_sec);\n timestamp.set_nanos(tv.tv_usec * 1000);\n\n Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.\n\n FILETIME ft;\n GetSystemTimeAsFileTime(&ft);\n UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;\n\n // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z\n // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.\n Timestamp timestamp;\n timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));\n timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));\n\n Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.\n\n long millis = System.currentTimeMillis();\n\n Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)\n .setNanos((int) ((millis % 1000) * 1000000)).build();\n\n Example 5: Compute Timestamp from Java `Instant.now()`.\n\n Instant now = Instant.now();\n\n Timestamp timestamp =\n Timestamp.newBuilder().setSeconds(now.getEpochSecond())\n .setNanos(now.getNano()).build();\n\n Example 6: Compute Timestamp from current time in Python.\n\n timestamp = Timestamp()\n timestamp.GetCurrentTime()\n\n # JSON Mapping\n\n In JSON format, the Timestamp type is encoded as a string in the\n [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the\n format is \"{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z\"\n where {year} is always expressed using four digits while {month}, {day},\n {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional\n seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),\n are optional. The \"Z\" suffix indicates the timezone (\"UTC\"); the timezone\n is required. A proto3 JSON serializer should always use UTC (as indicated by\n \"Z\") when printing the Timestamp type and a proto3 JSON parser should be\n able to accept both UTC and other timezones (as indicated by an offset).\n\n For example, \"2017-01-15T01:30:15.01Z\" encodes 15.01 seconds past\n 01:30 UTC on January 15, 2017.\n\n In JavaScript, one can convert a Date object to this format using the\n standard\n [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)\n method. In Python, a standard `datetime.datetime` object can be converted\n to this format using\n [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with\n the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use\n the Joda Time's [`ISODateTimeFormat.dateTime()`](\n http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()\n ) to obtain a formatter capable of generating timestamps in this format."
format: date-time
type: string
gitpod.v1.GetTeamResponse:
additionalProperties: false
properties:
team:
$ref: '#/components/schemas/gitpod.v1.Team'
title: team
title: GetTeamResponse
type: object
gitpod.v1.DeleteTeamResponse:
additionalProperties: false
title: DeleteTeamResponse
type: object
gitpod.v1.ListTeamsRequest.Filter:
additionalProperties: false
properties:
search:
description: search filters teams by name (case-insensitive substring match).
maxLength: 256
title: search
type: string
title: Filter
type: object
gitpod.v1.CreateTeamRequest:
additionalProperties: false
properties:
name:
maxLength: 80
minLength: 3
title: name
type: string
organizationId:
format: uuid
title: organization_id
type: string
title: CreateTeamRequest
type: object
gitpod.v1.CountResponse:
additionalProperties: false
description: "CountResponse represents a bounded count of matching records.\n When the actual count exceeds the counting limit, value is capped and\n relation is set to GREATER_THAN_OR_EQUAL."
properties:
relation:
$ref: '#/components/schemas/gitpod.v1.CountResponseRelation'
description: Indicates whether value is the exact total or a lower bound.
title: relation
value:
description: The count of matching records, capped at the server's counting limit.
format: int32
title: value
type: integer
title: CountResponse
type: object
gitpod.v1.UpdateTeamResponse:
additionalProperties: false
properties:
team:
$ref: '#/components/schemas/gitpod.v1.Team'
title: team
title: UpdateTeamResponse
type: object
gitpod.v1.TeamMember:
additionalProperties: false
description: TeamMember represents a user's membership in a team.
properties:
avatarUrl:
description: avatar_url is the user's avatar URL, populated at query time.
title: avatar_url
type: string
createdAt:
$ref: '#/components/schemas/google.protobuf.Timestamp'
title: created_at
id:
description: Unique identifier for the team membership.
format: uuid
title: id
type: string
name:
description: name is the user's display name, populated at query time.
title: name
type: string
teamId:
format: uuid
title: team_id
type: string
userId:
format: uuid
title: user_id
type: string
title: TeamMember
type: object
gitpod.v1.GetTeamRequest:
additionalProperties: false
properties:
teamId:
format: uuid
title: team_id
type: string
title: GetTeamRequest
type: object
gitpod.v1.CreateTeamResponse:
additionalProperties: false
properties:
team:
$ref: '#/components/schemas/gitpod.v1.Team'
title: team
title: CreateTeamResponse
type: object
securitySchemes:
bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http
x-tagGroups:
- name: gitpod.v1
tags:
- gitpod.v1.AccountService
- gitpod.v1.AgentService
- gitpod.v1.AgentSecurityService
- gitpod.v1.BillingService
- gitpod.v1.EditorService
- gitpod.v1.EnvironmentAutomationService
- gitpod.v1.EnvironmentService
- gitpod.v1.ErrorsService
- gitpod.v1.EventService
- gitpod.v1.GatewayService
- gitpod.v1.GroupService
- gitpod.v1.IdentityService
- gitpod.v1.InsightsService
- gitpod.v1.IntegrationService
- gitpod.v1.NotificationService
- gitpod.v1.OnaIntelligenceService
- gitpod.v1.OrganizationService
- gitpod.v1.PrebuildService
- gitpod.v1.ProjectService
- gitpod.v1.RunnerConfigurationService
- gitpod.v1.RunnerInteractionService
- gitpod.v1.RunnerManagerService
- gitpod.v1.RunnerService
- gitpod.v1.SecretService
- gitpod.v1.ServiceAccountService
- gitpod.v1.SessionService
- gitpod.v1.TeamService
- gitpod.v1.UsageService
- gitpod.v1.UserService
- gitpod.v1.WebhookService
- gitpod.v1.WorkflowService