curl 'https://api.gitpod.io/gitpod.experimental.v1.WorkspacesService/ListWorkspaces' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{}'
Gitpod public API
Access Tokens are currently in Alpha · Send feedback.
The Gitpod Public API grants direct access to Gitpod data for use cases such as integration into other 3rd party applications.
Authentication
To authenticate requests, the Gitpod API utilises Access Token. In the Gitpod Settings, you can view and manage your PAT Tokens (Private Beta).
Keep in mind that your access tokens have a lot of power, so protect them carefully! Avoid disclosing your private Access Tokens in areas that are open to the public, such as GitHub, client-side code, and so forth.
To Authenticate you will need to pass an Access Token as an Authorization request header bearer token in the format Bearer <YOUR_ACCESS_TOKEN>
.
Example cURL command:
curl 'https://api.gitpod.io/gitpod.experimental.v1.TeamsService/ListTeams' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{}'
API Reference
Resource: Workspaces
List all workspaces
Lists all the workspaces belongs to the authenticated user. Currently, it returns only the first page of the results.
- cURL
- Go
- Response
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
pageSize (Coming Soon) |
It is maximum number of results we expect | Int32 | false |
Response Parameters:
Parameter | Description | Type |
---|---|---|
nextPageToken |
Next Page Token | string |
workspaceId |
Workspace Id | string |
ownerId |
User Id | string |
projectId |
Project Id | string |
context |
contextUrl with details of git or prebuild or snapshot |
string |
status |
will return Instance Id if currently assigned Instance Id to this workspace. Empty when there is no Instance Id assigned | string |
Get a workspace
Returns a single workspace.
- cURL
- Go
- Response
curl 'https://api.gitpod.io/gitpod.experimental.v1.WorkspacesService/GetWorkspace' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{"workspaceId":"<WORKSPACE_ID>"}'
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
workspaceId |
Workspace Id | string | true |
Response Parameters:
Parameter | Description | Type |
---|---|---|
workspaceId |
Workspace Id | string |
ownerId |
User Id | string |
projectId |
Project Id | string |
context |
contextUrl with details of git or prebuild or snapshot |
string |
status |
will return Instance Id if currently assigned Instance Id to this workspace. Empty when there is no Instance Id assigned | string |
Create Workspace (Coming Soon)
Creates a new workspace from any context URL (Repository, Issues, Pull Requests, Files, etc.)
Start workspace (Coming Soon)
Starts an older workspace (instance).
Usage: StartWorkspace()
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
workspaceId |
Workspace Id that needs to be stopped | string | true |
Response Parameters:
Parameter | Description | Type |
---|---|---|
instanceId |
Instance Id | string |
workspaceUrl |
URL of the started workspace | string |
Stop workspace
Stops a running workspace (instance).
- cURL
curl 'https://api.gitpod.io/gitpod.experimental.v1.WorkspacesService/StopWorkspace' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{"workspaceId":"<WORKSPACE_ID>"}'
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
workspaceId |
Workspace Id that needs to be stopped | string | true |
Response: It stops the requested workspace.
Delete workspace
It deletes the workspace & also stops the workspace if it is running.
- cURL
curl 'https://api.gitpod.io/gitpod.experimental.v1.WorkspacesService/DeleteWorkspace' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{"workspaceId":"<WORKSPACE_ID>"}'
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
workspaceId |
Workspace Id that needs to be deleted | string | true |
Response: It deletes the requested workspace.
Resource: Teams
Create a team
Creates a team.
- cURL
- Response
curl 'https://api.gitpod.io/gitpod.experimental.v1.TeamsService/CreateTeam' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{"name":"<TEAM_NAME>"}'
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
name |
Team name | string | true |
Response Parameters:
Parameter | Description | Type |
---|---|---|
id |
UUID of Team | string |
name |
Name of team | string |
creationTime |
Creation time of team | string |
members |
List of members in a team | array |
Get a team
Returns a single team.
- cURL
- Go
- Response
curl 'https://api.gitpod.io/gitpod.experimental.v1.TeamsService/GetTeam' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{"teamId":"<TEAM_ID>"}'
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
teamId |
Team Id | string | true |
Response Parameters:
Parameter | Description | Type |
---|---|---|
id |
UUID of Team | string |
name |
Name of team | string |
creationTime |
Creation time of team | string |
members |
List of members in a team | array |
List all teams
Lists all the teams belongs to the authenticated user.
- cURL
- Go
- Response
curl 'https://api.gitpod.io/gitpod.experimental.v1.TeamsService/ListTeams' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{}'
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
pageSize |
It is maximum number of results we expect | Int32 | false |
Response Parameters:
Parameter | Description | Type |
---|---|---|
teams |
List of teams of a user | array |
Join a team
Joins a team.
- cURL
- Response
curl 'https://api.gitpod.io/gitpod.experimental.v1.TeamsService/JoinTeam' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{"invitationId":"<TEAM_INVITATION_ID>"}'
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
invitationId |
Team Invitation ID | string | true |
Response Parameters:
Parameter | Description | Type |
---|---|---|
id |
UUID of Team | string |
name |
Name of team | string |
creationTime |
Creation time of team | string |
members |
List of members in a team | array |
Reset team invitation
Resets the team invitation.
- cURL
- Response
curl 'https://api.gitpod.io/gitpod.experimental.v1.TeamsService/ResetTeamInvitation' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{"teamId":"<TEAM_ID>"}'
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
teamId |
Team Invitation ID | string | true |
Response Parameters:
Parameter | Description | Type |
---|---|---|
invitationId |
new Invitation Id of Team | string |
Update a team member role
Updates a team member role
- cURL
- Response
curl 'https://api.gitpod.io/gitpod.experimental.v1.TeamsService/UpdateTeamMember' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{"teamId":"<TEAM_ID>", "teamMember": {"userId":"<USER_ID>", "role":"TEAM_ROLE_OWNER"}}'
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
teamId |
Team name | string | true |
userId |
User ID of a team member being updated | string | true |
role |
Role of a team member: TEAM_ROLE_OWNER or TEAM_ROLE_MEMBER |
string | true |
Response Parameters:
Parameter | Description | Type |
---|---|---|
userId |
User ID of team member | string |
role |
New role of team | string |
Delete team member
Deletes a team member.
- cURL
curl 'https://api.gitpod.io/gitpod.experimental.v1.TeamsService/DeleteTeamMember' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{"teamId":"<TEAM_ID>", "teamMemberId": "<USER_ID>"}'
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
teamId |
Team name | string | true |
teamMemberId |
Id of team member being updated | string | true |
Response: It deletes the team member from the team.
Delete a team
Deletes a team.
- cURL
curl 'https://api.gitpod.io/gitpod.experimental.v1.TeamsService/DeleteTeam' \
-H 'content-type: application/json' \
-H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--data '{"teamId":"<TEAM_ID>"}'
Request Parameters:
Parameter | Description | Type | Required |
---|---|---|---|
teamId |
Team name | string | true |
Response: It deletes the requested team.
API language clients
Go
The following is an example of how to use the Go client library with the Public API for retrieving teams data. Replace the environment variable PERSONAL_PAT
with your own personal access token, for example: export PERSONAL_PAT=<your-personal-pat>
// Download the helper library using go get -u github.com/gitpod-io/gitpod/components/public-api/go
package main
import (
"context"
"fmt"
"os"
"github.com/bufbuild/connect-go"
"github.com/gitpod-io/gitpod/components/public-api/go/client"
v1 "github.com/gitpod-io/gitpod/components/public-api/go/experimental/v1"
)
func main() {
token := "<YOUR_ACCESS_TOKEN>"
gitpod, err := client.New(client.WithCredentials(token))
if err != nil {
fmt.Fprintf(os.Stderr, "Failed to construct gitpod client %v", err)
return
}
response, err := gitpod.Teams.ListTeams(context.Background(), connect.NewRequest(&v1.ListTeamsRequest{}))
if err != nil {
fmt.Fprintf(os.Stderr, "Failed to list teams %v", err)
return
}
fmt.Fprintf(os.Stdout, "Retrieved teams %v", response.Msg.GetTeams())
}
TypeScript
🚧 Under development