Gitpod API Reference | Projects

Projects

projects

Methods

Create Projects -> { createdProjects, failedProjects }

post/gitpod.v1.ProjectService/CreateProjects

Creates multiple projects in a single request.

Use this method to:

Onboard multiple repositories at once
Import a batch of projects during initial setup

Returns successfully created projects and details about any failures. Each project in the request is processed independently — partial success is possible.

Examples

Create multiple projects:

Creates several projects in one request.

projects:
  - name: "Frontend"
    initializer:
      specs:
        - git:
            remoteUri: "https://github.com/org/frontend"
  - name: "Backend"
    initializer:
      specs:
        - git:
            remoteUri: "https://github.com/org/backend"

Delete Projects -> { deletedProjectIds, failedProjects }

post/gitpod.v1.ProjectService/DeleteProjects

Deletes multiple projects in a single request.

Use this method to:

Remove multiple unused projects at once
Clean up projects in batch

Returns successfully deleted project IDs and details about any failures. Each project in the request is processed independently — partial success is possible.

Examples

Delete multiple projects:

Permanently removes several projects in one request.

projectIds:
  - "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  - "c1f23g7d-5d78-430e-b5b7-e0949c6eb158"

Update Projects -> { failedProjects, updatedProjects }

post/gitpod.v1.ProjectService/UpdateProjects

Updates multiple projects in a single request.

Use this method to:

Modify settings across multiple projects at once
Apply configuration changes in batch

Returns successfully updated projects and details about any failures. Each project in the request is processed independently — partial success is possible.

Examples

Update multiple projects:

Updates several projects in one request.

projects:
  - projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
    name: "Updated Frontend"
  - projectId: "c1f23g7d-5d78-430e-b5b7-e0949c6eb158"
    name: "Updated Backend"

Response fields

failedProjects: Array<{ error, index, projectId }>

Optional

failed_projects contains details about projects that failed to update

updatedProjects: Array<

Project

Optional

updated_projects contains the successfully updated projects

Request example

curl https://app.gitpod.io/api/gitpod.v1.ProjectService/UpdateProjects \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'

200Example

{
  "failedProjects": [
    {
      "error": "error",
      "index": 0,
      "projectId": "projectId"
    }
  ],
  "updatedProjects": [
    {
      "environmentClass": {
        "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "localRunner": true,
        "order": 0
      },
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "automationsFilePath": "automationsFilePath",
      "desiredPhase": "PROJECT_PHASE_UNSPECIFIED",
      "devcontainerFilePath": "devcontainerFilePath",
      "environmentClasses": [
        {
          "environmentClassId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "localRunner": true,
          "order": 0
        }
      ],
      "initializer": {
        "specs": [
          {
            "contextUrl": {
              "url": "https://example.com"
            },
            "git": {
              "checkoutLocation": "checkoutLocation",
              "cloneTarget": "cloneTarget",
              "remoteUri": "remoteUri",
              "targetMode": "CLONE_TARGET_MODE_UNSPECIFIED",
              "upstreamRemoteUri": "upstreamRemoteUri"
            }
          }
        ]
      },
      "metadata": {
        "createdAt": "2019-12-27T18:11:19.117Z",
        "creator": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "principal": "PRINCIPAL_UNSPECIFIED"
        },
        "name": "x",
        "organizationId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "updatedAt": "2019-12-27T18:11:19.117Z"
      },
      "prebuildConfiguration": {
        "enabled": true,
        "enableJetbrainsWarmup": true,
        "environmentClassIds": [
          "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
        ],
        "executor": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "principal": "PRINCIPAL_UNSPECIFIED"
        },
        "timeout": "+9125115.360s",
        "trigger": {
          "dailySchedule": {
            "hourUtc": 23
          }
        }
      },
      "recommendedEditors": {
        "editors": {
          "foo": {
            "versions": [
              "string"
            ]
          }
        }
      },
      "technicalDescription": "technicalDescription",
      "usedBy": {
        "subjects": [
          {
            "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
            "principal": "PRINCIPAL_UNSPECIFIED"
          }
        ],
        "totalSubjects": 0
      }
    }
  ]
}

Create Project -> { project }

post/gitpod.v1.ProjectService/CreateProject

Creates a new project with specified configuration.

Use this method to:

Set up development projects
Configure project environments
Define project settings
Initialize project content

Examples

Create basic project:

Creates a project with minimal configuration.

name: "Web Application"
initializer:
  specs:
    - git:
        remoteUri: "https://github.com/org/repo"

Create project with devcontainer:

Creates a project with custom development container.

name: "Backend Service"
initializer:
  specs:
    - git:
        remoteUri: "https://github.com/org/backend"
devcontainerFilePath: ".devcontainer/devcontainer.json"
automationsFilePath: ".gitpod/automations.yaml"

Create Project From Environment -> { project }

post/gitpod.v1.ProjectService/CreateProjectFromEnvironment

Creates a new project using an existing environment as a template.

Use this method to:

Clone environment configurations
Create projects from templates
Share environment setups

Examples

Create from environment:

Creates a project based on existing environment.

name: "Frontend Project"
environmentId: "07e03a28-65a5-4d98-b532-8ea67b188048"

Delete Project -> unknown

post/gitpod.v1.ProjectService/DeleteProject

Deletes a project permanently.

Use this method to:

Remove unused projects
Clean up test projects
Delete obsolete configurations

Examples

Delete project:

Permanently removes a project.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"

List Projects -> ProjectsPage<

Project

post/gitpod.v1.ProjectService/ListProjects

Lists projects with optional filtering.

Use this method to:

View all accessible projects
Browse project configurations
Monitor project status

Examples

List projects:

Shows all projects with pagination.
```
pagination:
  pageSize: 20
```

Get Project -> { project }

post/gitpod.v1.ProjectService/GetProject

Gets details about a specific project.

Use this method to:

View project configuration
Check project status
Get project metadata

Examples

Get project details:

Retrieves information about a specific project.
```
projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
```

Update Project -> { project }

post/gitpod.v1.ProjectService/UpdateProject

Updates a project's configuration.

Use this method to:

Modify project settings
Update environment class
Change project name
Configure initializers
Configure prebuild settings

Examples

Update project name:

Changes the project's display name.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
name: "New Project Name"

Enable prebuilds with daily schedule:

Configures prebuilds to run daily at 2 AM UTC.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
prebuildConfiguration:
  enabled: true
  environmentClassIds:
    - "b0e12f6c-4c67-429d-a4a6-d9838b5da041"
  timeout: "3600s"
  trigger:
    dailySchedule:
      hourUtc: 2

Domain types

EnvironmentInitializer = { specs }

EnvironmentInitializer specifies how an environment is to be initialized

Project = { environmentClass, id, automationsFilePath, 9 more... }

ProjectMetadata = { createdAt, creator, name, 2 more... }

ProjectPhase = "PROJECT_PHASE_UNSPECIFIED" | "PROJECT_PHASE_ACTIVE" | "PROJECT_PHASE_DELETED"

ProjectPrebuildConfiguration = { enabled, enableJetbrainsWarmup, environmentClassIds, 3 more... }

ProjectPrebuildConfiguration defines how prebuilds are created for a project. Prebuilds create environment snapshots that enable faster environment startup times.

RecommendedEditors = { editors }

RecommendedEditors contains the map of recommended editors and their versions.

Sort = { field, order }

SortOrder = "SORT_ORDER_UNSPECIFIED" | "SORT_ORDER_ASC" | "SORT_ORDER_DESC"

Projects

Environment Clases

projects.environmentClases

Methods

List Project Environment Classes -> ProjectEnvironmentClassesPage<

ProjectEnvironmentClass

post/gitpod.v1.ProjectService/ListProjectEnvironmentClasses

Lists environment classes of a project.

Use this method to:

View all environment classes of a project

Examples

List project environment classes:

Shows all environment classes of a project.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 20

Update Project Environment Classes -> unknown

post/gitpod.v1.ProjectService/UpdateProjectEnvironmentClasses

Updates all environment classes of a project.

Use this method to:

Modify all environment classea of a project

Examples

Update project environment classes:

Updates all environment classes for a project.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
projectEnvironmentClasses:
  - environmentClassId: "b0e12f6c-4c67-429d-a4a6-d9838b5da041"
    order: 0
  - localRunner: true
    order: 1

Projects

Policies

projects.policies

Methods

Create Project Policy -> { policy }

post/gitpod.v1.ProjectService/CreateProjectPolicy

Creates a new policy for a project.

Use this method to:

Set up access controls
Define group permissions
Configure role-based access

Examples

Create admin policy:

Grants admin access to a group.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
role: PROJECT_ROLE_ADMIN

Delete Project Policy -> unknown

post/gitpod.v1.ProjectService/DeleteProjectPolicy

Deletes a project policy.

Use this method to:

Remove access controls
Revoke permissions
Clean up policies

Examples

Delete policy:

Removes a group's access policy.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"

List Project Policies -> PoliciesPage<

ProjectPolicy

post/gitpod.v1.ProjectService/ListProjectPolicies

Lists policies for a project.

Use this method to:

View access controls
Check policy configurations
Audit permissions

Examples

List policies:

Shows all policies for a project.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 20

Update Project Policy -> { policy }

post/gitpod.v1.ProjectService/UpdateProjectPolicy

Updates an existing project policy.

Use this method to:

Modify access levels
Change group roles
Update permissions

Examples

Update policy role:

Changes a group's access level.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
groupId: "f53d2330-3795-4c5d-a1f3-453121af9c60"
role: PROJECT_ROLE_EDITOR

Domain types

ProjectPolicy = { groupId, role }

ProjectRole = "PROJECT_ROLE_UNSPECIFIED" | "PROJECT_ROLE_ADMIN" | "PROJECT_ROLE_USER" | 1 more...