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

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.

Method Example:

cURL cURL
Go Go
Response Response

cURL

curl 'https://api.gitpod.io/gitpod.experimental.v1.WorkspacesService/ListWorkspaces' \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data '{}'

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.

Method Example:

cURL cURL
Go Go
Response Response

cURL

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).

Method Example:

cURL cURL

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.

Method Example:

cURL cURL

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.

Method Example:

cURL cURL
Response Response

cURL

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.

Method Example:

cURL cURL
Go Go
Response Response

cURL

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.

Method Example:

cURL cURL
Go Go
Response Response

cURL

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.

Method Example:

cURL cURL
Response Response

cURL

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.

Method Example:

cURL cURL
Response Response

cURL

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

Method Example:

cURL cURL
Response Response

cURL

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.

Method Example:

cURL cURL

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.

Method Example:

cURL cURL

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>

language:

// 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

Gitpod public API

Authentication

API Reference

Resource: Workspaces

List all workspaces

Get a workspace

Create Workspace (Coming Soon)

Start workspace (Coming Soon)

Stop workspace

Delete workspace

Resource: Teams

Create a team

Get a team

List all teams

Join a team

Reset team invitation

Update a team member role

Delete team member

Delete a team

API language clients

Go

TypeScript

Was this helpful?