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 cURL
Response 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`, `rustrover`)	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 cURL
Response 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 cURL
Response 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 cURL
Response 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 cURL
Response 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 cURL
Response 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.

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 creationTime descending. 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.

Method example:

cURL cURL
Response Response

cURL

curl -X POST \
    "https://api.$GITPOD_DOMAIN/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:

Parameter	Description	Type	Required
`organizationId`	Organization ID	string	true
`pagination`	Pagination parameters	object	false
`from`	Start of the creationTime range	string	false
`to`	End of the creationTime range	string	false

Response: Returns a list of workspace sessions.

Resource: Organizations

Create an organization

Creates an organization.

Method example:

cURL cURL
Response 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 cURL
Response 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 cURL
Response 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 cURL
Response 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 cURL
Response 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 cURL
Response 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 cURL
Response 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 cURL
Response 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 cURL
Response 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.

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.

Method example:

cURL cURL
Response Response

cURL

curl -X POST \
  "https://api.$GITPOD_DOMAIN/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:

Parameter	Description	Type	Required
`organization_id`	The ID of the organization	string	true
`from`	The starting time range for the request (timestamp)	string (timestamp in ISO 8601 format)	false
`to`	The ending time range for the request (timestamp)	string (timestamp in ISO 8601 format)	false
`actor_id`	The ID of the user performing the action	string	false
`action`	The action performed	string	false
`pagination`	Pagination options for the request	object	false

Response Parameters:

Parameter	Description	Type
`pagination`	Pagination details for the response	object
`audit_logs`	List of audit logs that matched the query	array
`audit_logs[0].id`	The unique identifier of the audit log	string
`audit_logs[0].timestamp`	The time when the audit log was created	string (timestamp in ISO 8601 format)
`audit_logs[0].action`	The action that was performed	string
`audit_logs[0].organization_id`	The ID of the organization	string
`audit_logs[0].actor_id`	The ID of the user that performed the action	string
`audit_logs[0].args`	A serialized JSON array of arguments passed	string

Gitpod API

Authentication

Resource: Workspaces

Create and start a workspace

List all workspaces

Get a workspace

Start a workspace

Stop a workspace

Delete a workspace

List workspace sessions

Resource: Organizations

Create an organization

List all organizations

Get an organization

Join an organization

Reset organization invitation

Get list of all organization members

Update an organization member role

Delete or Remove an organization member

Delete an organization

Resource: Audit Logs

List audit logs

Was this helpful?