The Gitpod Public API grants direct access to Gitpod data for use cases such as integration into other 3rd party applications.

This document addresses a basic subset of the Gitpod Classic HTTP API. For more powerful access to Gitpod, check out Gitpod Flex and its API.

Authentication

To authenticate requests, the Gitpod API utilizes 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.

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:

ParameterDescriptionTypeRequired
contextUrl.urlContext URL ( Repository, Issues, Pull Request URL)stringtrue
contextUrl.workspaceClassWorkspace class (g1-standard or g1-large. Additionally, g1-xlarge or g1-xxlarge for Enterprise)stringtrue
contextUrl.editor.nameIDE to be used for the workspace (code, code-desktop, intellij, goland, phpstorm, pycharm, rubymine, webstorm, rider, clion, rustrover)stringfalse
contextUrl.editor.versionVersion of the editor you’d like to use (default: stable, option: latest)stringfalse
metadata.ownerIdUser ID of the ownerstringtrue
metadata.organizationIdOrganization IDstringtrue

Response Parameters:

ParameterDescriptionType
workspace.idThe ID of the workspacestring
workspace.metadataThe metadata of the workspaceWorkspaceMetadata
workspace.metadata.ownerIdThe ID of the user that owns the workspacestring
workspace.metadata.organizationIdThe ID of the organization that the workspace belongs tostring
workspace.metadata.configurationIdThe ID of the project or configuration that the workspace belongs tostring
workspace.metadata.nameThe name of the workspacestring
workspace.metadata.originalContextUrlThe original context URL of the workspacestring
workspace.specThe specifications of the workspaceWorkspaceSpec
workspace.spec.initializerInitializer specifications for the workspaceInitializerSpec
workspace.spec.initializer.specsArray of specifications for the initializer[InitializerSpecs] (array)
workspace.spec.initializer.specs[0].gitGit configuration for the initializerGitSpec
workspace.spec.typeThe type of the workspacestring
workspace.spec.portsArray of port configurations for the workspace[PortsSpec] (array)
workspace.spec.timeoutTimeout configuration for the workspaceTimeoutSpec
workspace.spec.admissionAdmission level for the workspacestring
workspace.spec.classResource class allocated to the workspacestring
workspace.spec.editorEditor configuration for the workspaceEditorSpec
workspace.statusThe status of the workspaceWorkspaceStatus
workspace.status.phaseCurrent phase of the workspacePhaseSpec
workspace.status.gitStatusGit status information for the workspaceGitStatusSpec
workspace.status.instanceIdThe instance ID of the workspacestring

List all workspaces

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

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:

ParameterDescriptionTypeRequired
organizationIdThe ID of the organization that the workspace belongs to.stringtrue
pinnedWhether to return only pinned workspaces.booleanfalse
searchTermA search term to filter the workspaces by.stringfalse
pagination.pageIt specifies the page number of the results we expect (default: 1)Int32false
pagination.pageSizeIt limits the maximum number of results we expect (default: 25, maximum: 100)Int32false

Response Parameters:

ParameterDescriptionType
pagination.totalTotal number of organizationsInt32
pagination.nextTokenNext page token for pagination, Empty if there are no more resultsstring
workspacesList of workspaces[]Workspace (array)
workspaces[0].idThe ID of the workspacestring
workspaces[0].metadataThe metadata of the workspaceWorkspaceMetadata
workspaces[0].metadata.ownerIdThe ID of the user that owns the workspacestring
workspaces[0].metadata.organizationIdThe ID of the organization that the workspace belongs tostring
workspaces[0].metadata.configurationIdThe ID of the project or configuration that the workspace belongs tostring
workspaces[0].metadata.nameThe name of the workspacestring
workspaces[0].metadata.originalContextUrlThe original context URL of the workspacestring
workspaces[0].specThe specifications of the workspaceWorkspaceSpec
workspaces[0].spec.initializerInitializer specifications for the workspaceInitializerSpec
workspaces[0].spec.initializer.specsArray of specifications for the initializer[InitializerSpecs] (array)
workspaces[0].spec.initializer.specs[0].gitGit configuration for the initializerGitSpec
workspaces[0].spec.typeThe type of the workspacestring
workspaces[0].spec.portsArray of port configurations for the workspace[PortsSpec] (array)
workspaces[0].spec.timeoutTimeout configuration for the workspaceTimeoutSpec
workspaces[0].spec.admissionAdmission level for the workspacestring
workspaces[0].spec.classResource class allocated to the workspacestring
workspaces[0].spec.editorEditor configuration for the workspaceEditorSpec
workspaces[0].statusThe status of the workspaceWorkspaceStatus
workspaces[0].status.phaseCurrent phase of the workspacePhaseSpec
workspaces[0].status.gitStatusGit status information for the workspaceGitStatusSpec
workspaces[0].status.instanceIdThe instance ID of the workspacestring

Get a workspace

Returns details about a specific workspace.

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:

ParameterDescriptionTypeRequired
workspaceIdWorkspace IDstringtrue

Response Parameters:

ParameterDescriptionType
workspace.idThe ID of the workspacestring
workspace.metadataThe metadata of the workspaceWorkspaceMetadata
workspace.metadata.ownerIdThe ID of the user that owns the workspacestring
workspace.metadata.organizationIdThe ID of the organization that the workspace belongs tostring
workspace.metadata.configurationIdThe ID of the project or configuration that the workspace belongs tostring
workspace.metadata.nameThe name of the workspacestring
workspace.metadata.originalContextUrlThe original context URL of the workspacestring
workspace.specThe specifications of the workspaceWorkspaceSpec
workspace.spec.initializerInitializer specifications for the workspaceInitializerSpec
workspace.spec.initializer.specsArray of specifications for the initializer[InitializerSpecs] (array)
workspace.spec.initializer.specs[0].gitGit configuration for the initializerGitSpec
workspace.spec.typeThe type of the workspacestring
workspace.spec.portsArray of port configurations for the workspace[PortsSpec] (array)
workspace.spec.timeoutTimeout configuration for the workspaceTimeoutSpec
workspace.spec.admissionAdmission level for the workspacestring
workspace.spec.classResource class allocated to the workspacestring
workspace.spec.editorEditor configuration for the workspaceEditorSpec
workspace.statusThe status of the workspaceWorkspaceStatus
workspace.status.phaseCurrent phase of the workspacePhaseSpec
workspace.status.gitStatusGit status information for the workspaceGitStatusSpec
workspace.status.instanceIdThe instance ID of the workspacestring

Start a workspace

Starts an older workspace (instance).

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:

ParameterDescriptionTypeRequired
workspaceIdID of the workspace to startstringtrue

Response Parameters: Returns the same response as GetWorkspace.

ParameterDescriptionType
workspace.idThe ID of the workspacestring
workspace.metadataThe metadata of the workspaceWorkspaceMetadata
workspace.metadata.ownerIdThe ID of the user that owns the workspacestring
workspace.metadata.organizationIdThe ID of the organization that the workspace belongs tostring
workspace.metadata.configurationIdThe ID of the project or configuration that the workspace belongs tostring
workspace.metadata.nameThe name of the workspacestring
workspace.metadata.originalContextUrlThe original context URL of the workspacestring
workspace.specThe specifications of the workspaceWorkspaceSpec
workspace.spec.initializerInitializer specifications for the workspaceInitializerSpec
workspace.spec.initializer.specsArray of specifications for the initializer[InitializerSpecs] (array)
workspace.spec.initializer.specs[0].gitGit configuration for the initializerGitSpec
workspace.spec.typeThe type of the workspacestring
workspace.spec.portsArray of port configurations for the workspace[PortsSpec] (array)
workspace.spec.timeoutTimeout configuration for the workspaceTimeoutSpec
workspace.spec.admissionAdmission level for the workspacestring
workspace.spec.classResource class allocated to the workspacestring
workspace.spec.editorEditor configuration for the workspaceEditorSpec
workspace.statusThe status of the workspaceWorkspaceStatus
workspace.status.phaseCurrent phase of the workspacePhaseSpec
workspace.status.gitStatusGit status information for the workspaceGitStatusSpec
workspace.status.instanceIdThe instance ID of the workspacestring

Stop a workspace

Stops a running workspace (instance).

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:

ParameterDescriptionTypeRequired
workspaceIdWorkspace ID that needs to be stoppedstringtrue

Response: It stops the requested workspace.


Delete a workspace

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

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:

ParameterDescriptionTypeRequired
workspaceIdWorkspace ID that needs to be deletedstringtrue

Response: It deletes the requested workspace.


List workspace sessions

If you are an organization owner, you can list all workspace sessions in the organization. A workspace session is tracked whenever a workspace is started until it is stopped.

The responses are paged, and you can specify the page size and page number. The responses are ordered by descending creationTime. You can filter the responses by creationTime range using the from and to arguments. If to is not specified, it defaults to now. If from is not specified, it defaults to 7 days before to.

curl -X POST \
    "https://api.gitpod.io/gitpod.v1.WorkspaceService/ListWorkspaceSessions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'content-type: application/json' \
    --data-raw '{
        "organizationId": "<ORGANIZATION_ID>",
        "pagination": {
            "pageSize": 20,
            "page": 0
        },
        "from": "2024-01-13T07:06:45.659Z",
        "to": "2024-07-13T07:06:48.659Z"
    }'
}'

Request Parameters:

ParameterDescriptionTypeRequired
organizationIdOrganization IDstringtrue
paginationPagination parametersobjectfalse
fromStart of the creationTime rangestringfalse
toEnd of the creationTime rangestringfalse

Response: Returns a list of workspace sessions.



Resource: Organizations

You can also view the protocol buffer definitions here for more details.

Create an organization

Creates an organization.

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:

ParameterDescriptionTypeRequired
nameOrganization namestringtrue

Response Parameters:

ParameterDescriptionType
idUUID of Organizationstring
nameName of Organizationstring
creationTimeCreation time of Organizationstring (timestamp in ISO 8601 format)

List all organizations

Lists all the organizations belonging to the authenticated user.

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:

ParameterDescriptionTypeRequired
pagination.pageIt specifies the page number of the results we expect (default: 1)Int32false
pagination.pageSizeIt limits the maximum number of results we expect (default: 25, maximum: 100)Int32false

Response Parameters:

ParameterDescriptionType
organizationsList of organizationsarray
organizations[0].idUUID of the organizationstring
organizations[0].nameName of the organizationstring
organizations[0].creationTimeCreation time of the organizationstring (timestamp in ISO 8601 format)
organizations[0].slugSlug of the organizationstring
pagination.totalTotal number of organizationsInt32
pagination.nextTokenNext page token for pagination, Empty if there are no more resultsstring

Get an organization

Returns the details about a single organization.

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:

ParameterDescriptionTypeRequired
organizationIdOrganization IDstringtrue

Response Parameters:

ParameterDescriptionType
idUUID of Organizationstring
nameName of Organizationstring
creationTimeCreation time of Organizationstring (timestamp in ISO 8601 format)

Delete an organization

Deletes an organization.

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:

ParameterDescriptionTypeRequired
organizationIdOrganization ID that needs to be deletedstringtrue

Response: It deletes the requested organization.

Get an organization’s settings

Returns the settings of an organization.

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

Request Parameters:

ParameterDescriptionTypeRequired
organizationIdOrganization IDstringtrue

Response Parameters:

ParameterDescriptionType
settingsSettings of an organizationObject
settings.workspaceSharingDisabledWhether workspace sharing is disabledBoolean
settings.defaultWorkspaceImageDefault workspace imageString
settings.allowedWorkspaceClassesIDs of workspace classes allowed to be usedArray
settings.restrictedEditorNamesList of restricted editor namesArray
settings.pinnedEditorVersionsPinned versions for corresponding editorsMap
settings.defaultRoleDefault role for new membersString
settings.timeoutSettingsTimeout settings (see related section in Organization Policies)Object
settings.timeoutSettings.inactivityInactivity timeoutString
settings.timeoutSettings.denyUserTimeoutsWhether to deny user timeoutsBoolean
settings.roleRestrictionsRole restrictionsArray
settings.maxParallelRunningWorkspacesMaximum number of parallel running workspaces (see related section in Organization Policies)Int32
settings.onboardingSettingsOnboarding settings (see the Organization Onboarding documentation)Object
settings.onboardingSettings.internalLinkInternal link for onboardingString
settings.onboardingSettings.welcomeMessageWelcome message for onboardingObject
settings.onboardingSettings.welcomeMessage.enabledWhether to show the welcome message to new organization members.Boolean
settings.onboardingSettings.welcomeMessage.messageWelcome message for onboardingString
settings.onboardingSettings.welcomeMessage.featuredMemberIdID of the member whose avatar will be displayed in the welcome messageString
settings.onboardingSettings.welcomeMessage.featuredMemberResolvedAvatarUrlAvatar URL of the member whose avatar will be displayed in the welcome messageString
settings.onboardingSettings.recommendedRepositoriesConfiguration IDs of recommended repositories for onboardingArray
settings.annotateGitCommitsWhether to annotate Git commits (see Git commit annotation)Boolean

Update an organization’s settings

Performs a partial update of an organization’s settings.

curl -X POST \
  'https://api.gitpod.io/gitpod.v1.OrganizationService/UpdateOrganizationSettings' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORG_ID>",
  "settings": {
    "defaultWorkspaceImage": "docker.io/gitpod/workspace-full"
  }
}'

For the response parameters under settings, see the Get an organization’s settings section.

Request Parameters:

ParameterDescriptionTypeRequired
organizationIdOrganization IDStringYes
workspaceSharingDisabledWhether workspace sharing is disabledBoolean
settings.defaultWorkspaceImageDefault workspace imageString
allowedWorkspaceClassesIDs of workspace classes allowed to be usedArray
updateAllowedWorkspaceClassesWhether to update allowed workspace classesBoolean
restrictedEditorNamesList of restricted editor namesArray
updateRestrictedEditorNamesWhether to update restricted editor namesBoolean
pinnedEditorVersionsPinned versions for corresponding editorsMap
updatePinnedEditorVersionsWhether to update pinned editor versionsBoolean
defaultRoleDefault role for new membersString
timeoutSettingsTimeout settings (see related section in Organization Policies)Object
timeoutSettings.inactivityInactivity timeoutString
timeoutSettings.denyUserTimeoutsWhether to deny user timeoutsBoolean
roleRestrictionsRole restrictionsArray
updateRoleRestrictionsWhether to update role restrictionsBoolean
maxParallelRunningWorkspacesMaximum number of parallel running workspaces (see related section in Organization Policies)Int32
onboardingSettingsOnboarding settings (see the Organization Onboarding documentation)Object
onboardingSettings.internalLinkInternal link for onboardingString
onboardingSettings.welcomeMessageWelcome message for onboardingObject
onboardingSettings.welcomeMessage.enabledWhether to show the welcome message to new organization members.Boolean
onboardingSettings.welcomeMessage.messageWelcome message for onboardingString
onboardingSettings.welcomeMessage.featuredMemberIdID of the member whose avatar will be displayed in the welcome messageString
onboardingSettings.recommendedRepositoriesConfiguration IDs of recommended repositories for onboardingArray
annotateGitCommitsWhether to annotate Git commits (see Git commit annotation)Boolean

Response Parameters:

ParameterDescriptionType
settingsUpdated settingsObject

Join an organization

Joins an organization.

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:

ParameterDescriptionTypeRequired
invitationIdOrganization Invitation IDstringtrue

Response Parameters:

ParameterDescriptionType
organizationIdUUID of Teamstring

Reset organization invitation

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

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:

ParameterDescriptionTypeRequired
organizationIdOrganization IDstringtrue

Response Parameters:

ParameterDescriptionType
invitationIdNew invitation id of organizationstring

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.

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:

ParameterDescriptionTypeRequired
organizationIdOrganization IDstringtrue

Response Parameters:

ParameterDescriptionType
membersList of members in an organizationarray
members[0].userIdUser ID of the memberstring
members[0].roleRole of the member (ORGANIZATION_ROLE_OWNER, ORGANIZATION_ROLE_MEMBER, ORGANIZATION_ROLE_COLLABORATOR)string
members[0].memberSinceTime since member is part of organizationstring (timestamp in ISO 8601 format)
members[0].avatarUrlAvatar URL of memberstring
members[0].fullNameFull name of memberstring
members[0].emailEmail ID of memberstring
pagination.totalTotal number of organizationsInt32
pagination.nextTokenNext page token for pagination, Empty if there are no more resultsstring

Update an organization member role

Updates an organization member role

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:

ParameterDescriptionTypeRequired
organizationIdTeam namestringtrue
userIdUser ID of a team member being updatedstringtrue
roleRole of a team member: (ORGANIZATION_ROLE_OWNER, ORGANIZATION_ROLE_MEMBER, ORGANIZATION_ROLE_COLLABORATOR)stringtrue

Response Parameters:

ParameterDescriptionType
member.userIdUser ID of the memberstring
members.roleNew role of the member (ORGANIZATION_ROLE_OWNER, ORGANIZATION_ROLE_MEMBER, ORGANIZATION_ROLE_COLLABORATOR)string
member.memberSinceTime since member is part of organizationstring (timestamp in ISO 8601 format)
member.avatarUrlAvatar URL of memberstring
member.fullNameFull name of memberstring
member.emailEmail ID of member

Delete or Remove an organization member

Deletes/Removes an organization member.

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:

ParameterDescriptionTypeRequired
organizationIdOrganization IDstringtrue
userIdUser ID of organization member being removedstringtrue

Response: Empty JSON object


Resource: Audit Logs

This is only available in Gitpod Enterprise.

List audit logs

Lists audit logs for the organization of the authenticated user. This API requires organization owner permissions.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.AuditLogService/ListAuditLogs" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
    "organizationId": "<ORGANIZATION_ID>",
    "pagination": {
        "pageSize": 200,
        "page": 0
    },
    "from": "2024-01-13T07:06:45.659Z",
    "to": "2024-07-13T07:06:48.659Z"
}'

Request Parameters:

ParameterDescriptionTypeRequired
organization_idThe ID of the organizationstringtrue
fromThe starting time range for the request (timestamp)string (timestamp in ISO 8601 format)false
toThe ending time range for the request (timestamp)string (timestamp in ISO 8601 format)false
actor_idThe ID of the user performing the actionstringfalse
actionThe action performedstringfalse
paginationPagination options for the requestobjectfalse

Response Parameters:

ParameterDescriptionType
paginationPagination details for the responseobject
audit_logsList of audit logs that matched the queryarray
audit_logs[0].idThe unique identifier of the audit logstring
audit_logs[0].timestampThe time when the audit log was createdstring (timestamp in ISO 8601 format)
audit_logs[0].actionThe action that was performedstring
audit_logs[0].organization_idThe ID of the organizationstring
audit_logs[0].actor_idThe ID of the user that performed the actionstring
audit_logs[0].argsA serialized JSON array of arguments passedstring

Resource: Configurations (aka Repository Settings)

Configurations are the API nomenclature used for interacting with Repositories.

You can also view the protocol buffer definitions here for more details.

Create Configuration

Imports a repository into Gitpod.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.ConfigurationService/CreateConfiguration" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORGANIZATION_ID>",
  "cloneUrl": "<CLONE_URL>"
  }'

Request Parameters:

ParameterDescriptionTypeRequired
organizationIdThe ID of the organizationstringtrue
cloneUrlThe URL of the repository to importstringtrue
nameThe display name of the configurationstringfalse

Response Parameters:

ParameterDescriptionType
configurationThe created configurationobject

Get Configuration

Retrieves a single configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.ConfigurationService/GetConfiguration" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "configurationId": "<CONFIGURATION_ID>"
  }'

Request Parameters:

ParameterDescriptionTypeRequired
configurationIdThe ID of the configurationstringtrue

Response Parameters:

ParameterDescriptionType
configurationThe retrieved configurationobject
configuration.idThe ID of the configurationstring
configuration.organizationIdThe ID of the organizationstring
configuration.nameThe display name of the configurationstring
configuration.cloneUrlThe clone URL of the repositorystring
configuration.creationTimeThe time when the configuration was createdstring (timestamp in ISO 8601 format)
configuration.prebuildSettingsThe prebuild settings for the configurationobject
configuration.workspaceSettingsThe workspace settings for the configurationobject

List Configurations

Lists all configurations for an organization.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.ConfigurationService/ListConfigurations" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "organizationId": "<ORGANIZATION_ID>",
  "pagination": {
    "token": "<NEXT_TOKEN>"
  },
  "sort": [
    {"field":"name","order":"SORT_ORDER_ASC"}
  ]
  }'

Request Parameters:

ParameterDescriptionTypeRequired
organizationIdThe ID of an organizationstringtrue
paginationPagination details for the requestobjectfalse
pagination.tokenThe next token for pagination (value of nextToken from the previous response)stringfalse
sortSorting details for the requestarrayfalse
sort[0].fieldThe field to sort by (either name or creationTime)stringtrue
sort[0].orderThe order to sort by (either SORT_ORDER_ASC or SORT_ORDER_DESC)stringtrue

Response Parameters:

ParameterDescriptionType
configurationsA list of configurationsarray
configurations[0].idThe ID of a configurationstring
configurations[0].organizationIdThe ID of an organizationstring
configurations[0].nameThe display name of a configurationstring
configurations[0].cloneUrlThe clone URL of a repositorystring
configurations[0].creationTimeThe time when a configuration was createdstring (timestamp in ISO 8601 format)
configurations[0].prebuildSettingsThe prebuild settings for a configurationobject
configurations[0].workspaceSettingsThe workspace settings for a configurationobject
paginationPagination details for the responseobject
pagination.nextTokenThe next token for paginationstring

Update Configuration

Updates a configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.ConfigurationService/UpdateConfiguration" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "configurationId": "<CONFIGURATION_ID>",
  "name": "<NEW_NAME>"
  }'

Request Parameters:

ParameterDescriptionTypeRequired
configurationIdThe ID of a configurationstringtrue
nameThe display name of a configurationstringfalse
prebuildSettingsThe prebuild settings for a configurationobjectfalse
workspaceSettingsThe workspace settings for a configurationobjectfalse

Response Parameters:

ParameterDescriptionType
configurationThe updated configurationobject
configuration.idThe ID of the updated configurationstring
configuration.organizationIdThe ID of the organization the configuration belongs tostring
configuration.nameThe display name of the updated configurationstring
configuration.cloneUrlThe clone URL of the repository the configuration belongs tostring
configuration.creationTimeThe time when the configuration was createdstring (timestamp in ISO 8601 format)
configuration.prebuildSettingsThe prebuild settings for the configurationobject
configuration.workspaceSettingsThe workspace settings for the configurationobject

Delete Configuration

Deletes a configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.ConfigurationService/DeleteConfiguration" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "configurationId": "<CONFIGURATION_ID>"
  }'

Request Parameters:

ParameterDescriptionTypeRequired
configurationIdThe ID of a configurationstringtrue

Response Parameters: none

Resource: Environment Variables

GItpod offers programmatic access to manage environment variables of Imported repositories.

You can also view the protocol buffer definitions here for more details.

Create Configuration Environment Variable

Creates an environment variable for a configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.EnvironmentVariableService/CreateConfigurationEnvironmentVariable" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "configurationId": "<CONFIGURATION_ID>",
  "name": "<NAME>",
  "value": "<VALUE>",
  "admission": "<ADMISSION>"
  }'

Request Parameters:

ParameterDescriptionTypeRequired
configurationIdThe ID of a configurationstringtrue
nameThe name of an environment variablestringtrue
valueThe value of an environment variablestringtrue
admissionThe “visibility” of an environment variable. Either ENVIRONMENT_VARIABLE_ADMISSION_EVERYWHERE (default) or ENVIRONMENT_VARIABLE_ADMISSION_PREBUILDstringfalse

Response Parameters:

ParameterDescriptionType
environmentVariableThe created environment variableobject
environmentVariable.idThe ID of the created environment variablestring
environmentVariable.nameThe name of the created environment variablestring
environmentVariable.configurationIdThe ID of the configuration the environment variable belongs tostring
environmentVariable.admissionThe “visibility” of the created environment variable. Either ENVIRONMENT_VARIABLE_ADMISSION_EVERYWHERE or ENVIRONMENT_VARIABLE_ADMISSION_PREBUILDstring

List Configuration Environment Variables

Lists all environment variables for a configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.EnvironmentVariableService/ListConfigurationEnvironmentVariables" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "configurationId": "<CONFIGURATION_ID>"
  }'

Request Parameters:

ParameterDescriptionTypeRequired
configurationIdThe ID of a configurationstringtrue

Response Parameters:

ParameterDescriptionType
environmentVariablesA list of environment variablesarray
environmentVariables[0].idThe ID of an environment variablestring
environmentVariables[0].nameThe name of an environment variablestring
environmentVariables[0].configurationIdThe ID of a configurationstring
environmentVariables[0].admissionThe “visibility” of an environment variable. Either ENVIRONMENT_VARIABLE_ADMISSION_EVERYWHERE or ENVIRONMENT_VARIABLE_ADMISSION_PREBUILDstring

Delete Configuration Environment Variable

Deletes an environment variable for a configuration.

curl -X POST \
  "https://api.gitpod.io/gitpod.v1.EnvironmentVariableService/DeleteConfigurationEnvironmentVariable" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data-raw '{
  "environment_variable_id": "<ENVIRONMENT_VARIABLE_ID>"
  }'

Request Parameters:

ParameterDescriptionTypeRequired
environment_variable_idThe ID of an environment variablestringtrue

Response Parameters: none