Gitpod API

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

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 -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/ListOrganizations' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{}'

Resource: Workspaces

Create and start a workspace

Creates and starts a new workspace from a context URL such as repositories, issues, pull requests, files URL.

Method example:
  • cURL
  • Response
cURL 
curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/CreateAndStartWorkspace' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "contextUrl": {
    "url": "<CONTEXT_URL>",
    "workspaceClass": "g1-standard",
    "editor": {
      "name": "code",
      "version": "latest"
    }
  },
  "metadata": {
    "ownerId": "<USER_ID>",
    "organizationId": "<ORG_ID>"
  }
}'

Request Parameters:

Parameter Description Type Required
contextUrl.url Context URL ( Repository, Issues, Pull Request URL) string true
contextUrl.workspaceClass Workspace class (g1-standard or g1-large. Additionally, g1-xlarge or g1-xxlarge for Enterprise) string true
contextUrl.editor.name IDE to be used for the workspace (code, code-desktop, intellij, goland, phpstorm, pycharm, rubymine, webstorm, rider, clion) string false
contextUrl.editor.version Version of the editor you’d like to use (default: stable, option: latest) string false
metadata.ownerId User ID of the owner string true
metadata.organizationId Organization ID string true

Response Parameters:

Parameter Description Type
workspace.id The ID of the workspace string
workspace.metadata The metadata of the workspace WorkspaceMetadata
workspace.metadata.ownerId The ID of the user that owns the workspace string
workspace.metadata.organizationId The ID of the organization that the workspace belongs to string
workspace.metadata.configurationId The ID of the project or configuration that the workspace belongs to string
workspace.metadata.name The name of the workspace string
workspace.metadata.originalContextUrl The original context URL of the workspace string
workspace.spec The specifications of the workspace WorkspaceSpec
workspace.spec.initializer Initializer specifications for the workspace InitializerSpec
workspace.spec.initializer.specs Array of specifications for the initializer [InitializerSpecs] (array)
workspace.spec.initializer.specs[0].git Git configuration for the initializer GitSpec
workspace.spec.type The type of the workspace string
workspace.spec.ports Array of port configurations for the workspace [PortsSpec] (array)
workspace.spec.timeout Timeout configuration for the workspace TimeoutSpec
workspace.spec.admission Admission level for the workspace string
workspace.spec.class Resource class allocated to the workspace string
workspace.spec.editor Editor configuration for the workspace EditorSpec
workspace.status The status of the workspace WorkspaceStatus
workspace.status.phase Current phase of the workspace PhaseSpec
workspace.status.gitStatus Git status information for the workspace GitStatusSpec
workspace.status.instanceId The instance ID of the workspace string

List all workspaces

Lists all the workspaces belongs to the authenticated user in the required organization.

Method example:
  • cURL
  • Response
cURL 
curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/ListWorkspaces' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>"
}'

Request Parameters:

Parameter Description Type Required
organizationId The ID of the organization that the workspace belongs to. string true
pinned Whether to return only pinned workspaces. boolean false
searchTerm A search term to filter the workspaces by. string false
pagination.page It specifies the page number of the results we expect (default: 1) Int32 false
pagination.pageSize It limits the maximum number of results we expect (default: 25, maximum: 100) Int32 false

Response Parameters:

Parameter Description Type
pagination.total Total number of organizations Int32
pagination.nextToken Next page token for pagination, Empty if there are no more results string
workspaces List of workspaces []Workspace (array)
workspaces[0].id The ID of the workspace string
workspaces[0].metadata The metadata of the workspace WorkspaceMetadata
workspaces[0].metadata.ownerId The ID of the user that owns the workspace string
workspaces[0].metadata.organizationId The ID of the organization that the workspace belongs to string
workspaces[0].metadata.configurationId The ID of the project or configuration that the workspace belongs to string
workspaces[0].metadata.name The name of the workspace string
workspaces[0].metadata.originalContextUrl The original context URL of the workspace string
workspaces[0].spec The specifications of the workspace WorkspaceSpec
workspaces[0].spec.initializer Initializer specifications for the workspace InitializerSpec
workspaces[0].spec.initializer.specs Array of specifications for the initializer [InitializerSpecs] (array)
workspaces[0].spec.initializer.specs[0].git Git configuration for the initializer GitSpec
workspaces[0].spec.type The type of the workspace string
workspaces[0].spec.ports Array of port configurations for the workspace [PortsSpec] (array)
workspaces[0].spec.timeout Timeout configuration for the workspace TimeoutSpec
workspaces[0].spec.admission Admission level for the workspace string
workspaces[0].spec.class Resource class allocated to the workspace string
workspaces[0].spec.editor Editor configuration for the workspace EditorSpec
workspaces[0].status The status of the workspace WorkspaceStatus
workspaces[0].status.phase Current phase of the workspace PhaseSpec
workspaces[0].status.gitStatus Git status information for the workspace GitStatusSpec
workspaces[0].status.instanceId The instance ID of the workspace string

Get a workspace

Returns details about a specific workspace.

Method example:
  • cURL
  • Response
cURL 
curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/GetWorkspace' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "workspaceId": "<WORKSPACE_ID>"
}'

Request Parameters:

Parameter Description Type Required
workspaceId Workspace ID string true

Response Parameters:

Parameter Description Type
workspace.id The ID of the workspace string
workspace.metadata The metadata of the workspace WorkspaceMetadata
workspace.metadata.ownerId The ID of the user that owns the workspace string
workspace.metadata.organizationId The ID of the organization that the workspace belongs to string
workspace.metadata.configurationId The ID of the project or configuration that the workspace belongs to string
workspace.metadata.name The name of the workspace string
workspace.metadata.originalContextUrl The original context URL of the workspace string
workspace.spec The specifications of the workspace WorkspaceSpec
workspace.spec.initializer Initializer specifications for the workspace InitializerSpec
workspace.spec.initializer.specs Array of specifications for the initializer [InitializerSpecs] (array)
workspace.spec.initializer.specs[0].git Git configuration for the initializer GitSpec
workspace.spec.type The type of the workspace string
workspace.spec.ports Array of port configurations for the workspace [PortsSpec] (array)
workspace.spec.timeout Timeout configuration for the workspace TimeoutSpec
workspace.spec.admission Admission level for the workspace string
workspace.spec.class Resource class allocated to the workspace string
workspace.spec.editor Editor configuration for the workspace EditorSpec
workspace.status The status of the workspace WorkspaceStatus
workspace.status.phase Current phase of the workspace PhaseSpec
workspace.status.gitStatus Git status information for the workspace GitStatusSpec
workspace.status.instanceId The instance ID of the workspace string

Start a workspace

Starts an older workspace (instance).

Method example:
  • cURL
  • Response
cURL 
curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/StartWorkspace' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "workspaceId": "<WORKSPACE_ID>"
}'

Request Parameters:

Parameter Description Type Required
workspaceId ID of the workspace to start string true

Response Parameters: Returns the same response as GetWorkspace.

Parameter Description Type
workspace.id The ID of the workspace string
workspace.metadata The metadata of the workspace WorkspaceMetadata
workspace.metadata.ownerId The ID of the user that owns the workspace string
workspace.metadata.organizationId The ID of the organization that the workspace belongs to string
workspace.metadata.configurationId The ID of the project or configuration that the workspace belongs to string
workspace.metadata.name The name of the workspace string
workspace.metadata.originalContextUrl The original context URL of the workspace string
workspace.spec The specifications of the workspace WorkspaceSpec
workspace.spec.initializer Initializer specifications for the workspace InitializerSpec
workspace.spec.initializer.specs Array of specifications for the initializer [InitializerSpecs] (array)
workspace.spec.initializer.specs[0].git Git configuration for the initializer GitSpec
workspace.spec.type The type of the workspace string
workspace.spec.ports Array of port configurations for the workspace [PortsSpec] (array)
workspace.spec.timeout Timeout configuration for the workspace TimeoutSpec
workspace.spec.admission Admission level for the workspace string
workspace.spec.class Resource class allocated to the workspace string
workspace.spec.editor Editor configuration for the workspace EditorSpec
workspace.status The status of the workspace WorkspaceStatus
workspace.status.phase Current phase of the workspace PhaseSpec
workspace.status.gitStatus Git status information for the workspace GitStatusSpec
workspace.status.instanceId The instance ID of the workspace string

Stop a workspace

Stops a running workspace (instance).

Method example:
  • cURL
  • Response
cURL 
curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/StopWorkspace' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "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 a workspace

It deletes the workspace & also stops the workspace if it is running.

Method example:
  • cURL
  • Response
cURL 
curl -X POST \
  'https://api.gitpod.io/gitpod.v1.WorkspaceService/DeleteWorkspace' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "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: Organizations

Create an organization

Creates an organization.

Method example:
  • cURL
  • Response
cURL 
curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/CreateOrganization' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "name": "<ORG_NAME>"
}'

Request Parameters:

Parameter Description Type Required
name Organization name string true

Response Parameters:

Parameter Description Type
id UUID of Organization string
name Name of Organization string
creationTime Creation time of Organization string (timestamp in ISO 8601 format)

List all organizations

Lists all the organizations belonging to the authenticated user.

Method example:
  • cURL
  • Response
cURL 
curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/ListOrganizations' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{}'

Request Parameters:

Parameter Description Type Required
pagination.page It specifies the page number of the results we expect (default: 1) Int32 false
pagination.pageSize It limits the maximum number of results we expect (default: 25, maximum: 100) Int32 false

Response Parameters:

Parameter Description Type
organizations List of organizations array
organizations[0].id UUID of the organization string
organizations[0].name Name of the organization string
organizations[0].creationTime Creation time of the organization string (timestamp in ISO 8601 format)
organizations[0].slug Slug of the organization string
pagination.total Total number of organizations Int32
pagination.nextToken Next page token for pagination, Empty if there are no more results string

Get an organization

Returns the details about a single organization.

Method example:
  • cURL
  • Response
cURL 
curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/GetOrganization' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>"
}'

Request Parameters:

Parameter Description Type Required
organizationId Organization ID string true

Response Parameters:

Parameter Description Type
id UUID of Organization string
name Name of Organization string
creationTime Creation time of Organization string (timestamp in ISO 8601 format)

Join an organization

Joins an organization.

Method example:
  • cURL
  • Response
cURL 
curl  -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/JoinOrganization' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "invitationId": "<ORG_INVITATION_ID>"
}'

Request Parameters:

Parameter Description Type Required
invitationId Organization Invitation ID string true

Response Parameters:

Parameter Description Type
organizationId UUID of Team string

Reset organization invitation

Resets/recreates the ID of an organization’s invitation.

Method example:
  • cURL
  • Response
cURL 
curl  -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/ResetOrganizationInvitation' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>"
}'

Request Parameters:

Parameter Description Type Required
organizationId Organization ID string true

Response Parameters:

Parameter Description Type
invitationId New invitation id of organization string

Get list of all organization members

Returns the list of all organization members. And it returns the role of each member, role differs in three categories Owner, Member, Collaborator. Learn more about Member roles.

Method example:
  • cURL
  • Response
cURL 
curl  -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/ListOrganizationMembers' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>"
}'

Request Parameters:

Parameter Description Type Required
organizationId Organization ID string true

Response Parameters:

Parameter Description Type
members List of members in an organization array
members[0].userId User ID of the member string
members[0].role Role of the member (ORGANIZATION_ROLE_OWNER, ORGANIZATION_ROLE_MEMBER, ORGANIZATION_ROLE_COLLABORATOR) string
members[0].memberSince Time since member is part of organization string (timestamp in ISO 8601 format)
members[0].avatarUrl Avatar URL of member string
members[0].fullName Full name of member string
members[0].email Email ID of member string
pagination.total Total number of organizations Int32
pagination.nextToken Next page token for pagination, Empty if there are no more results string

Update an organization member role

Updates an organization member role

Method example:
  • cURL
  • Response
cURL 
curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/UpdateOrganizationMember' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>",
    "userId": "<USER_ID>",
    "role": "<ORG_MEMBER_ROLE>"
}'

Request Parameters:

Parameter Description Type Required
organizationId Team name string true
userId User ID of a team member being updated string true
role Role of a team member: (ORGANIZATION_ROLE_OWNER, ORGANIZATION_ROLE_MEMBER, ORGANIZATION_ROLE_COLLABORATOR) string true

Response Parameters:

Parameter Description Type
member.userId User ID of the member string
members.role New role of the member (ORGANIZATION_ROLE_OWNER, ORGANIZATION_ROLE_MEMBER, ORGANIZATION_ROLE_COLLABORATOR) string
member.memberSince Time since member is part of organization string (timestamp in ISO 8601 format)
member.avatarUrl Avatar URL of member string
member.fullName Full name of member string
member.email Email ID of member

Delete or Remove an organization member

Deletes/Removes an organization member.

Method example:
  • cURL
  • Response
cURL 
curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/DeleteOrganizationMember' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>",
  "userId": "<USER_ID>"
}'

Request Parameters:

Parameter Description Type Required
organizationId Organization ID string true
userId User ID of organization member being removed string true

Response: Empty JSON object


Delete an organization

Deletes an organization.

Method example:
  • cURL
  • Response
cURL 
curl  -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/DeleteOrganization' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>"
}'

Request Parameters:

Parameter Description Type Required
organizationId Organization ID that needs to be deleted string true

Response: It deletes the requested organization.

Was this helpful?

Previous Next