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
  • Go
  • 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
  • Go
  • 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 '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 '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
  • 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
  • Go
  • 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
  • Go
  • 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
  • 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
  • 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
  • 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 '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 '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 icon language: 
go
// 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

Was this helpful?