### Start Environment

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Starts a specified Gitpod environment.

```APIDOC
## POST /gitpod.v1.EnvironmentService/StartEnvironment

### Description
Starts a Gitpod environment.

### Method
POST

### Endpoint
/gitpod.v1.EnvironmentService/StartEnvironment

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for starting an environment.
```

--------------------------------

### Install Gitpod Python SDK

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Install the SDK using pip. To use the aiohttp async backend, install with the extra dependency.

```sh
pip install gitpod-sdk
# with aiohttp async backend
pip install "gitpod-sdk[aiohttp]"
```

--------------------------------

### Install Gitpod SDK

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/README.md

Install the Gitpod SDK from PyPI using pip.

```sh
pip install gitpod-sdk
```

--------------------------------

### Install Gitpod SDK with aiohttp support

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/README.md

Install the Gitpod SDK with aiohttp support from PyPI.

```sh
pip install gitpod-sdk[aiohttp]
```

--------------------------------

### Install SDK from Local Wheel File

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/CONTRIBUTING.md

Install the Gitpod Python SDK using a previously built wheel file. Replace './path-to-wheel-file.whl' with the actual path to the generated .whl file.

```sh
pip install ./path-to-wheel-file.whl
```

--------------------------------

### Install SDK from Git Repository

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/CONTRIBUTING.md

Install the Gitpod Python SDK directly from its GitHub repository using pip. This is useful for testing unreleased changes.

```sh
pip install git+ssh://git@github.com/gitpod-io/gitpod-sdk-python.git
```

--------------------------------

### Add and Run a New Example

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/CONTRIBUTING.md

Create a new Python file in the 'examples/' directory, make it executable, and then run it against your API. The shebang line ensures it runs with the correct Python interpreter managed by Rye.

```python
# add an example to examples/<your-example>.py

#!/usr/bin/env -S rye run python
…
```

```sh
$ chmod +x examples/<your-example>.py
# run the example against your api
$ ./examples/<your-example>.py
```

--------------------------------

### Start Service

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Starts a specific service. This method requires parameters to identify the service to be started.

```APIDOC
## POST /gitpod.v1.EnvironmentAutomationService/StartService

### Description
Starts a specific service.

### Method
POST

### Endpoint
/gitpod.v1.EnvironmentAutomationService/StartService

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for starting a service.

### Request Example
```json
{
  "example": "request body for start service"
}
```

### Response
#### Success Response (200)
- **object** (object) - Response indicating the result of the start operation.

### Response Example
```json
{
  "example": "response body for start service"
}
```
```

--------------------------------

### Start Agent Execution

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Starts a new Gitpod agent execution. This method is part of the Agents API.

```python
client.agents.start_execution(**params) -> AgentStartExecutionResponse
```

--------------------------------

### Run a background service and stream logs

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Starts a background service in a Gitpod environment and streams its logs. Ensure the environment is set up with the necessary ports and the service commands are correctly defined.

```python
import asyncio
from gitpod import AsyncGitpod
import gitpod.lib as util

client = AsyncGitpod()

async def main(cleanup: util.Disposables):
    env_class = await util.find_most_used_environment_class(client)
    environment = (await client.environments.create(spec={
        "desired_phase": "ENVIRONMENT_PHASE_RUNNING",
        "machine": {"class": env_class.id},
        "ports": [{"name": "app", "port": 8080, "admission": "ADMISSION_LEVEL_EVERYONE"}],
    })).environment
    cleanup.adda(lambda: client.environments.delete(environment_id=environment.id))

    state = util.EnvironmentState(client, environment.id)
    cleanup.adda(lambda: state.close())
    await state.wait_until_running()

    log_stream = await util.run_service(
        client,
        environment.id,
        metadata={"name": "Dev Server", "description": "Vite dev server", "reference": "dev-server"},
        spec={"commands": {"start": "npm run dev", "ready": "curl -sf http://localhost:8080"}},
    )

    port_url = await state.wait_for_port_url(8080)
    print(f"App is live at: {port_url}")

    async for line in log_stream:
        print(line)

import asyncio
asyncio.run(util.with_disposables(main))
```

--------------------------------

### Install Development Dependencies with Pip

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/CONTRIBUTING.md

If not using Rye, install development dependencies using pip by referencing the locked requirements file. Ensure a virtual environment is active.

```sh
pip install -r requirements-dev.lock
```

--------------------------------

### Environments Lifecycle

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Demonstrates the full lifecycle of a Gitpod environment, including creation from a repository, retrieval, listing, updating, stopping, starting, creating an environment token, creating from a project, and deletion.

```APIDOC
## Environments — `client.environments`

Create, list, start, stop, update, and delete cloud development environments.

```python
import os
import asyncio
from gitpod import AsyncGitpod
from gitpod.types.environment_initializer_param import Spec

client = AsyncGitpod()

async def lifecycle_demo():
    # Create an environment from a GitHub repository
    create_resp = await client.environments.create(
        spec={
            "desired_phase": "ENVIRONMENT_PHASE_RUNNING",
            "content": {
                "initializer": {
                    "specs": [Spec(context_url={"url": "https://github.com/gitpod-io/empty"})]
                }
            },
            "machine": {"class": "<environment-class-id>"},
            "ports": [{"name": "web", "port": 3000, "admission": "ADMISSION_LEVEL_EVERYONE"}],
        }
    )
    env_id = create_resp.environment.id
    print(f"Created: {env_id}")

    # Retrieve current state
    env = (await client.environments.retrieve(environment_id=env_id)).environment
    print(f"Phase: {env.status.phase}")

    # List all environments (auto-paginated)
    async for env in client.environments.list():
        print(f"  {env.id} — {env.status.phase if env.status else 'unknown'}")

    # Update the environment name
    await client.environments.update(environment_id=env_id, metadata={"name": "my-env"})

    # Stop, then start again
    await client.environments.stop(environment_id=env_id)
    await client.environments.start(environment_id=env_id)

    # Create an access token for direct API calls from inside the environment
    token_resp = await client.environments.create_environment_token(environment_id=env_id)
    print(f"Environment token: {token_resp.access_token}")

    # Create an environment from a project template
    from_proj = await client.environments.create_from_project(project_id="<project-id>")
    print(f"From project: {from_proj.environment.id}")

    # Permanently delete
    await client.environments.delete(environment_id=env_id)

asyncio.run(lifecycle_demo())
```
```

--------------------------------

### Start Workflow Execution

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Starts a new execution of a workflow. Accepts parameters to configure the execution.

```APIDOC
## POST /gitpod.v1.WorkflowService/StartWorkflow

### Description
Starts a new execution of a workflow.

### Method
POST

### Endpoint
/gitpod.v1.WorkflowService/StartWorkflow

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for starting a workflow execution.
```

--------------------------------

### Start Agent Execution

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Starts a new agent execution. This method initiates a new instance of an agent task.

```APIDOC
## POST /gitpod.v1.AgentService/StartAgent

### Description
Starts a new agent execution.

### Method
POST

### Endpoint
/gitpod.v1.AgentService/StartAgent

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for starting the agent execution.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **AgentStartExecutionResponse** (object) - The response containing details of the started agent execution.

### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Start Gitpod Workflow Execution

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Initiates a new execution of a Gitpod workflow. Requires start execution parameters.

```python
client.automations.start_execution(**params) -> AutomationStartExecutionResponse
```

--------------------------------

### Manage Automation Services in Gitpod Environments

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Provides functionality to create, start, stop, list, and delete background services within a Gitpod environment. Services are defined with commands for starting, readiness checks, and can be triggered by lifecycle events.

```python
import asyncio
from gitpod import AsyncGitpod

client = AsyncGitpod()

async def main():
    env_id = "<environment-id>"

    # Create a background service
    service = (await client.environments.automations.services.create(
        environment_id=env_id,
        metadata={
            "name": "Postgres",
            "description": "PostgreSQL database",
            "reference": "postgres-svc",
        },
        spec={
            "commands": {
                "start": "docker run --rm -p 5432:5432 -e POSTGRES_PASSWORD=secret postgres:16",
                "ready": "pg_isready -h localhost",
            },
        },
    )).service
    print(f"Service created: {service.id}")

    # Start / stop
    await client.environments.automations.services.start(id=service.id)

    # List services
    for svc in (await client.environments.automations.services.list(
        filter={"environment_ids": [env_id]}
    )).services:
        print(f"  {svc.metadata.name}: {svc.status.phase if svc.status else 'unknown'}")

    await client.environments.automations.services.stop(id=service.id)
    await client.environments.automations.services.delete(id=service.id)

asyncio.run(main())

```

--------------------------------

### Configure Organization SSO with Python SDK

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Configure SAML/OIDC single sign-on for an organization. This snippet provides a starting point for configuring SSO. Requires a Gitpod client instance.

```python
from gitpod import Gitpod

client = Gitpod()

org_id = "<organization-id>"


```

--------------------------------

### Retrieve Account Info, Get SSO Login URL, List Joinable Organizations, List SSO Logins

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Shows how to fetch account details, generate an SSO login URL for a given email, list organizations that the account can join, and enumerate existing SSO logins.

```python
from gitpod import Gitpod

client = Gitpod()

# Get account info
account = client.accounts.retrieve().account
print(f"Account: {account.id}")

# Get the SSO login URL for an email address
sso_url = client.accounts.get_sso_login_url(
    return_to="https://gitpod.io",
    email="alice@corp.example.com",
).login_url
print(f"SSO URL: {sso_url}")

# List organizations the account can join
for org in client.accounts.list_joinable_organizations():
    print(f"  {org.organization_name} ({org.organization_id})")

# List existing SSO logins
for login in client.accounts.list_sso_logins():
    print(f"  provider={login.provider_id} email={login.email}")
```

--------------------------------

### Get Authenticated User, User by ID, List PATs, Set Dotfiles, Suspend User

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Demonstrates retrieving current user information, fetching a user by ID, listing personal access tokens, configuring a dotfiles repository, and suspending a user. Note that suspending a user is an admin-only operation.

```python
from gitpod import Gitpod

client = Gitpod()

# Get the currently authenticated user
me = client.users.get_authenticated_user().user
print(f"Me: {me.id} / {me.name}")

# Get any user by ID
user = client.users.get_user(user_id="<user-id>").user
print(f"User: {user.name}")

# List personal access tokens
for pat in client.users.pats.list(user_id=me.id):
    print(f"  PAT: {pat.id} — read_only={pat.read_only}")

# Set a dotfiles repository for the current user
client.users.dotfiles.set(
    user_id=me.id,
    dotfiles_git_url="https://github.com/me/dotfiles",
)

# Suspend a user (admin only)
client.users.set_suspended(user_id="<user-id>", suspended=True)
```

--------------------------------

### Sync Dependencies with Rye

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/CONTRIBUTING.md

After manually installing Rye, use this command to synchronize all project dependencies, including development features.

```sh
rye sync --all-features
```

--------------------------------

### Manage AI Agent Executions

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Start, manage, and communicate with AI agent executions within environments. Requires environment and prompt IDs.

```python
import asyncio
from gitpod import AsyncGitpod

client = AsyncGitpod()

async def main():
    # Start an agent execution
    resp = await client.agents.start_execution(
        environment_id="<environment-id>",
        spec={
            "prompt_id": "<prompt-id>",
        },
    )
    execution_id = resp.execution_id
    print(f"Agent execution started: {execution_id}")

    # Retrieve execution details
    detail = await client.agents.retrieve_execution(agent_execution_id=execution_id)
    print(f"Status: {detail.execution.status.phase if detail.execution.status else 'unknown'}")

    # Send a follow-up message to the running agent
    await client.agents.send_to_execution(
        agent_execution_id=execution_id,
        message={"content": "Please also run the linter after the tests."},
    )

    # List all executions
    for ex in client.agents.list_executions():
        print(f"  {ex.id}")

    # Stop the agent
    await client.agents.stop_execution(agent_execution_id=execution_id)

    # Manage reusable prompts
    prompt_resp = await client.agents.create_prompt(
        metadata={"name": "Code Review Prompt", "description": "Reviews PRs"},
        spec={"content": "Review the latest PR diff and summarize changes."},
    )
    print(f"Prompt: {prompt_resp.prompt.id}")

asyncio.run(main())
```

--------------------------------

### Automation Services Management

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Create, start, stop, list, and delete long-running background services within a Gitpod environment, such as databases or development servers. This enables robust and automated service management.

```APIDOC
## Automation Services — `client.environments.automations.services`

Create and manage long-running background services inside an environment (e.g. databases, dev servers).

```python
import asyncio
from gitpod import AsyncGitpod

client = AsyncGitpod()

async def main():
    env_id = "<environment-id>"

    # Create a background service
    service = (await client.environments.automations.services.create(
        environment_id=env_id,
        metadata={
            "name": "Postgres",
            "description": "PostgreSQL database",
            "reference": "postgres-svc",
        },
        spec={
            "commands": {
                "start": "docker run --rm -p 5432:5432 -e POSTGRES_PASSWORD=secret postgres:16",
                "ready": "pg_isready -h localhost",
            },
        },
    )).service
    print(f"Service created: {service.id}")

    # Start / stop
    await client.environments.automations.services.start(id=service.id)

    # List services
    for svc in (await client.environments.automations.services.list(
        filter={"environment_ids": [env_id]}
    )).services:
        print(f"  {svc.metadata.name}: {svc.status.phase if svc.status else 'unknown'}")

    await client.environments.automations.services.stop(id=service.id)
    await client.environments.automations.services.delete(id=service.id)

asyncio.run(main())
```
```

--------------------------------

### Upsert Environment Automations with AsyncGitpod

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Configures or updates automations for a Gitpod environment using a YAML-like structure. This is useful for defining services and tasks that should run automatically within an environment, such as starting databases or running build commands.

```python
import asyncio
from gitpod import AsyncGitpod

client = AsyncGitpod()

async def main():
    result = await client.environments.automations.upsert(
        environment_id="<environment-id>",
        automations_file={
            "services": {
                "database": {
                    "commands": {
                        "start": "docker run -p 5432:5432 postgres:16",
                        "ready": "pg_isready -h localhost",
                    },
                    "triggered_by": [{"postDevcontainerStart": {}}],
                }
            },
            "tasks": {
                "build": {
                    "command": "npm ci && npm run build",
                    "triggered_by": [{"postDevcontainerStart": {}}],
                }
            },
        },
    )
    print(f"Updated automations version: {result}")

asyncio.run(main())

```

--------------------------------

### Trigger and List Prebuilds

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Initiate a prebuild for a project to prepare environments and list existing prebuilds associated with a project. Requires project ID and context URL.

```python
prebuild = client.prebuilds.create(
    project_id="<project-id>",
    context_url="https://github.com/my-org/my-app",
).prebuild
print(f"Prebuild: {prebuild.id} — {prebuild.status.phase if prebuild.status else 'unknown'}")
```

```python
for pb in client.prebuilds.list(filter={"project_ids": ["<project-id>"]}):
    print(f"  {pb.id} — {pb.status.phase if pb.status else 'unknown'}")
```

--------------------------------

### Create and List Projects

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Create new projects from repository URLs and list existing projects. Project metadata and initializer specs are required for creation.

```python
project = client.projects.create(
    metadata={"name": "My App", "description": "Main application"},
    initializer={
        "specs": [{"context_url": {"url": "https://github.com/my-org/my-app"}}]
    },
).project
print(f"Project: {project.id}")
```

```python
for proj in client.projects.list():
    print(f"  {proj.id} — {proj.metadata.name if proj.metadata else 'unnamed'}")
```

--------------------------------

### Bulk Create Projects

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Efficiently create multiple projects simultaneously by providing a list of project configurations. Each project requires metadata and initializer specs.

```python
bulk_resp = client.projects.bulk_create(
    projects=[
        {"metadata": {"name": "Service A"}, "initializer": {"specs": [{"context_url": {"url": "https://github.com/org/service-a"}}]}},
        {"metadata": {"name": "Service B"}, "initializer": {"specs": [{"context_url": {"url": "https://github.com/org/service-b"}}]}},
    ]
)
print(f"Bulk created: {len(bulk_resp.projects)} projects")
```

--------------------------------

### Manage Organizations and Memberships with Python SDK

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Create and manage organizations, memberships, SSO, SCIM, custom domains, and policies. This snippet covers creating an org, retrieving details, listing members, setting roles, creating invites, updating policies, leaving an org, and deleting an org. Requires a Gitpod client instance.

```python
from gitpod import Gitpod

client = Gitpod()

# Create an organization
org = client.organizations.create(name="Acme Corp").organization
print(f"Created org: {org.id}")

# Retrieve org details
org_detail = client.organizations.retrieve(organization_id=org.id).organization
print(f"Name: {org_detail.name}")

# List members (auto-paginated)
for member in client.organizations.list_members(organization_id=org.id):
    print(f"  {member.user_id} — {member.role}")

# Promote a member to admin
client.organizations.set_role(
    organization_id=org.id,
    user_id="<user-id>",
    role="ORGANIZATION_ROLE_ADMIN",
)

# Create an invite link
invite = client.organizations.invites.create(organization_id=org.id).invite
print(f"Invite URL: {invite.invite_url}")

# Set organization policies
client.organizations.policies.update(
    organization_id=org.id,
    allowed_editor_ids=["code", "cursor"],
    max_parallel_running_environments=10,
)

# Leave the organization
client.organizations.leave(user_id="<user-id>")

# Delete the org
client.organizations.delete(organization_id=org.id)
```

--------------------------------

### Create Environment From Project

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Creates a new Gitpod environment based on an existing project.

```APIDOC
## POST /gitpod.v1.EnvironmentService/CreateEnvironmentFromProject

### Description
Creates a new Gitpod environment from a project.

### Method
POST

### Endpoint
/gitpod.v1.EnvironmentService/CreateEnvironmentFromProject

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating an environment from a project.
```

--------------------------------

### Determine Installed Gitpod SDK Version

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/README.md

Check the installed version of the Gitpod SDK at runtime by accessing the `__version__` attribute of the `gitpod` module. This is useful for debugging or ensuring compatibility.

```python
import gitpod
print(gitpod.__version__)
```

--------------------------------

### Initialize Gitpod SDK Clients

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Instantiate synchronous or asynchronous clients. The SDK automatically reads the GITPOD_API_KEY environment variable. Custom configurations for tokens, timeouts, retries, and HTTP proxies are supported. Use a context manager for automatic connection closing.

```python
import os
import asyncio
import httpx
from gitpod import Gitpod, AsyncGitpod, DefaultHttpxClient, DefaultAioHttpClient

# Synchronous client (reads GITPOD_API_KEY from environment)
client = Gitpod()

# Explicit token, custom timeout and retry policy
client = Gitpod(
    bearer_token=os.environ["GITPOD_API_KEY"],
    timeout=30.0,
    max_retries=3,
)

# Async client with httpx (default)
async_client = AsyncGitpod()

# Async client with aiohttp backend
async def main():
    async with AsyncGitpod(http_client=DefaultAioHttpClient()) as client:
        identity = await client.identity.get_authenticated_identity()
        print(identity.organization_id)

asyncio.run(main())

# Custom HTTP proxy / transport
client = Gitpod(
    base_url="https://api.gitpod.io",
    http_client=DefaultHttpxClient(
        proxy="http://proxy.example.com:8080",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

# Context-manager (auto-closes HTTP connections)
with Gitpod() as client:
    print(client.identity.get_authenticated_identity().organization_id)
```

--------------------------------

### Create Environment from Project

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Instantiate a new Gitpod environment directly from an existing project. Requires the project ID.

```python
env = client.environments.create_from_project(project_id=project.id).environment
print(f"Environment from project: {env.id}")
```

--------------------------------

### Agents

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Start, manage, and communicate with AI agent executions running inside environments.

```APIDOC
## Agents — `client.agents`

Start, manage, and communicate with AI agent executions running inside environments.

```python
import asyncio
from gitpod import AsyncGitpod

client = AsyncGitpod()

async def main():
    # Start an agent execution
    resp = await client.agents.start_execution(
        environment_id="<environment-id>",
        spec={
            "prompt_id": "<prompt-id>",
        },
    )
    execution_id = resp.execution_id
    print(f"Agent execution started: {execution_id}")

    # Retrieve execution details
    detail = await client.agents.retrieve_execution(agent_execution_id=execution_id)
    print(f"Status: {detail.execution.status.phase if detail.execution.status else 'unknown'}")

    # Send a follow-up message to the running agent
    await client.agents.send_to_execution(
        agent_execution_id=execution_id,
        message={"content": "Please also run the linter after the tests."},
    )

    # List all executions
    for ex in client.agents.list_executions():
        print(f"  {ex.id}")

    # Stop the agent
    await client.agents.stop_execution(agent_execution_id=execution_id)

    # Manage reusable prompts
    prompt_resp = await client.agents.create_prompt(
        metadata={"name": "Code Review Prompt", "description": "Reviews PRs"},
        spec={"content": "Review the latest PR diff and summarize changes."},
    )
    print(f"Prompt: {prompt_resp.prompt.id}")

asyncio.run(main())
```
```

--------------------------------

### Create Project From Environment

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Creates a new Gitpod project based on an existing environment configuration. Requires specific parameters.

```python
client.projects.create_from_environment(**params) -> ProjectCreateFromEnvironmentResponse
```

--------------------------------

### Get Announcement Banner

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Retrieves the announcement banner for an organization. Requires banner retrieval parameters.

```APIDOC
## POST /gitpod.v1.OrganizationService/GetAnnouncementBanner

### Description
Retrieves the announcement banner for an organization.

### Method
POST

### Endpoint
/gitpod.v1.OrganizationService/GetAnnouncementBanner

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for retrieving the announcement banner.

### Request Example
```json
{
  "example": "request body for get announcement banner"
}
```

### Response
#### Success Response (200)
- **banner** (AnnouncementBannerGetResponse) - Details of the announcement banner.

### Response Example
```json
{
  "example": "response body for get announcement banner"
}
```
```

--------------------------------

### Retrieve Group

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Retrieves details for a specific group. Use this to get information about an existing group.

```APIDOC
## POST /gitpod.v1.GroupService/GetGroup

### Description
Retrieves a specific group.

### Method
POST

### Endpoint
/gitpod.v1.GroupService/GetGroup

### Parameters
#### Query Parameters
- **params** (object) - Required - Parameters for retrieving a group.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **GroupRetrieveResponse** (object) - The response object after retrieving a group.
```

--------------------------------

### Create Project From Environment

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Creates a new Gitpod project based on an existing environment configuration.

```APIDOC
## POST /gitpod.v1.ProjectService/CreateProjectFromEnvironment

### Description
Creates a new Gitpod project from an environment.

### Method
POST

### Endpoint
/gitpod.v1.ProjectService/CreateProjectFromEnvironment

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating a project from an environment.

### Request Example
```json
{
  "params": { ... }
}
```

### Response
#### Success Response (200)
- **ProjectCreateFromEnvironmentResponse** (object) - Details of the created project from the environment.
```

--------------------------------

### Get SSO Login URL

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Generates a URL for Single Sign-On (SSO) login. Accepts optional parameters.

```APIDOC
## POST /gitpod.v1.AccountService/GetSSOLoginURL

### Description
Generates a URL for Single Sign-On (SSO) login.

### Method
POST

### Endpoint
/gitpod.v1.AccountService/GetSSOLoginURL

### Parameters
#### Query Parameters
- **params** (object) - Optional - Parameters for generating the SSO login URL.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **AccountGetSSOLoginURLResponse** (object) - The SSO login URL and related information.

### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Bootstrap Development Environment with Rye

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/CONTRIBUTING.md

Run this script to automatically set up the development environment using Rye, which manages Python versions and dependencies.

```sh
./scripts/bootstrap
```

--------------------------------

### run_service

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Starts a background service within an environment and streams its logs. This is useful for running development servers or other long-running processes.

```APIDOC
## `run_service` — start a background service and stream its logs

### Description
Starts a background service within an environment and streams its logs. This is useful for running development servers or other long-running processes.

### Parameters
- `client` (AsyncGitpod): An instance of the asynchronous Gitpod client.
- `environment_id` (str): The ID of the environment where the service will run.
- `metadata` (dict): Metadata for the service, including name, description, and reference.
- `spec` (dict): Specification for the service, including commands to start and readiness checks.

### Returns
- An asynchronous iterator yielding log lines from the service.
```

--------------------------------

### Prebuilds

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Trigger prebuilds to pre-initialize environments for faster startup, with warm-pool support.

```APIDOC
## Prebuilds — `client.prebuilds`

Trigger prebuilds to pre-initialize environments for faster startup, with warm-pool support.

### Trigger Prebuild

```python
prebuild = client.prebuilds.create(
    project_id="<project-id>",
    context_url="https://github.com/my-org/my-app",
).prebuild
```

### List Prebuilds

```python
for pb in client.prebuilds.list(filter={"project_ids": ["<project-id>"]}):
    print(f"  {pb.id} — {pb.status.phase if pb.status else 'unknown'}")
```

### Create Warm Pool

```python
warm_pool = client.prebuilds.create_warm_pool(
    prebuild_id=prebuild.id,
    spec={"min_size": 2, "max_size": 5},
).warm_pool
```

### Cancel Prebuild

```python
client.prebuilds.cancel(prebuild_id=prebuild.id)
```
```

--------------------------------

### Retrieve Environment Class

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Retrieves details of a specific environment class. Use this to get information about an existing custom environment.

```APIDOC
## POST /gitpod.v1.RunnerConfigurationService/GetEnvironmentClass

### Description
Retrieves an environment class.

### Method
POST

### Endpoint
/gitpod.v1.RunnerConfigurationService/GetEnvironmentClass

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for retrieving the environment class.
```

--------------------------------

### Create Warm Pool for Prebuilds

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Set up a warm pool to maintain a specified number of pre-warmed environments ready for use. Requires the prebuild ID and desired pool size.

```python
warm_pool = client.prebuilds.create_warm_pool(
    prebuild_id=prebuild.id,
    spec={"min_size": 2, "max_size": 5},
).warm_pool
print(f"Warm pool: {warm_pool.id}")
```

--------------------------------

### List Prebuilds

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Lists all prebuilds associated with the workspace.

```APIDOC
## POST /gitpod.v1.PrebuildService/ListPrebuilds

### Description
Lists all prebuilds associated with the workspace.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/ListPrebuilds

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for listing prebuilds.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **SyncPrebuildsPage[Prebuild]** (object) - A paginated list of prebuilds.

### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Get SSO Login URL

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Generate a Single Sign-On (SSO) login URL using the `get_sso_login_url` method. Ensure parameters are provided as keyword arguments.

```python
client.accounts.get_sso_login_url(**params) -> AccountGetSSOLoginURLResponse
```

--------------------------------

### Manage Environment Lifecycle with AsyncGitpod

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Demonstrates the full lifecycle of a Gitpod environment, from creation to deletion. Requires an environment class ID and a project ID for specific operations. Ensure you have the necessary permissions and configurations in your Gitpod account.

```python
import os
import asyncio
from gitpod import AsyncGitpod
from gitpod.types.environment_initializer_param import Spec

client = AsyncGitpod()

async def lifecycle_demo():
    # Create an environment from a GitHub repository
    create_resp = await client.environments.create(
        spec={
            "desired_phase": "ENVIRONMENT_PHASE_RUNNING",
            "content": {
                "initializer": {
                    "specs": [Spec(context_url={"url": "https://github.com/gitpod-io/empty"})]
                }
            },
            "machine": {"class": "<environment-class-id>"},
            "ports": [{"name": "web", "port": 3000, "admission": "ADMISSION_LEVEL_EVERYONE"}],
        }
    )
    env_id = create_resp.environment.id
    print(f"Created: {env_id}")

    # Retrieve current state
    env = (await client.environments.retrieve(environment_id=env_id)).environment
    print(f"Phase: {env.status.phase}")

    # List all environments (auto-paginated)
    async for env in client.environments.list():
        print(f"  {env.id} — {env.status.phase if env.status else 'unknown'}")

    # Update the environment name
    await client.environments.update(environment_id=env_id, metadata={"name": "my-env"})

    # Stop, then start again
    await client.environments.stop(environment_id=env_id)
    await client.environments.start(environment_id=env_id)

    # Create an access token for direct API calls from inside the environment
    token_resp = await client.environments.create_environment_token(environment_id=env_id)
    print(f"Environment token: {token_resp.access_token}")

    # Create an environment from a project template
    from_proj = await client.environments.create_from_project(project_id="<project-id>")
    print(f"From project: {from_proj.environment.id}")

    # Permanently delete
    await client.environments.delete(environment_id=env_id)

asyncio.run(lifecycle_demo())

```

--------------------------------

### Environments API - Pagination

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Demonstrates automatic and manual pagination for listing environments using the client.environments interface.

```APIDOC
## Pagination

All list methods return auto-paginating iterators. Manual page control is also available.

```python
import asyncio
from gitpod import AsyncGitpod

client = AsyncGitpod()

async def main():
    # Automatic: iterates all pages transparently
    async for env in client.environments.list():
        print(env.id)

    # Manual: inspect page metadata
    page = await client.environments.list(pagination={"page_size": 10})
    print(f"Next cursor: {page.pagination.next_token if page.pagination else 'none'}")
    for env in page.environments:
        print(f"  {env.id}")

    if page.has_next_page():
        next_page = await page.get_next_page()
        print(f"Next page has {len(next_page.environments)} items")

asyncio.run(main())
```
```

--------------------------------

### Synchronous Gitpod API Usage

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/README.md

Instantiate the synchronous Gitpod client and make a call to get the authenticated identity. The bearer token is read from the GITPOD_API_KEY environment variable by default.

```python
import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)

response = client.identity.get_authenticated_identity()
print(response.organization_id)
```

--------------------------------

### Create and Manage SSO Configurations

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Use this to create, list, update, and delete SSO configurations for an organization. Ensure the organization ID and provider details are correctly set.

```python
sso = client.organizations.sso_configurations.create(
    organization_id=org_id,
    provider_type="SSO_CONFIGURATION_PROVIDER_TYPE_OIDC",
    issuer_url="https://sso.corp.example.com",
    client_id="gitpod-client-id",
    client_secret="gitpod-client-secret",
    email_domain="corp.example.com",
).sso_configuration
print(f"SSO config: {sso.id}")
```

```python
for cfg in client.organizations.sso_configurations.list(organization_id=org_id):
    print(f"  {cfg.id} — {cfg.state}")
```

```python
client.organizations.sso_configurations.update(
    id=sso.id,
    state="SSO_CONFIGURATION_STATE_ACTIVE",
)
```

```python
client.organizations.sso_configurations.delete(id=sso.id)
```

--------------------------------

### List All Editors, Retrieve Specific Editor, Resolve Editor Launch URL

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Demonstrates enumerating all available IDEs, fetching details for a specific editor like 'code' (VS Code), and resolving the launch URL for a given editor and environment.

```python
from gitpod import Gitpod

client = Gitpod()

# List all editors
for editor in client.editors.list():
    print(f"{editor.id} — {editor.display_name}")

# Retrieve a specific editor
ed = client.editors.retrieve(editor_id="code").editor
print(f"VS Code: {ed.id} ({ed.display_name})")

# Resolve the launch URL for an editor + environment
url_resp = client.editors.resolve_url(
    editor_id="code",
    environment_id="<environment-id>",
)
print(f"Launch URL: {url_resp.url}")
```

--------------------------------

### Create Project

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Creates a new Gitpod project. This method accepts various parameters to configure the new project.

```APIDOC
## POST /gitpod.v1.ProjectService/CreateProject

### Description
Creates a new Gitpod project.

### Method
POST

### Endpoint
/gitpod.v1.ProjectService/CreateProject

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating a project.

### Request Example
```json
{
  "params": { ... }
}
```

### Response
#### Success Response (200)
- **ProjectCreateResponse** (object) - Details of the created project.
```

--------------------------------

### Asynchronous Gitpod API Usage

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/README.md

Instantiate the asynchronous Gitpod client and make a call to get the authenticated identity using await. The bearer token is read from the GITPOD_API_KEY environment variable by default.

```python
import os
import asyncio
from gitpod import AsyncGitpod

client = AsyncGitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)


async def main() -> None:
    response = await client.identity.get_authenticated_identity()
    print(response.organization_id)


asyncio.run(main())
```

--------------------------------

### Upsert Environment Automations

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Upserts the automations YAML file to declaratively define tasks and services within an environment. This allows for automated setup and execution of services and tasks upon environment creation or update.

```APIDOC
## Environment Automations — `client.environments.automations`

Upsert the automations YAML file to declaratively define tasks and services within an environment.

```python
import asyncio
from gitpod import AsyncGitpod

client = AsyncGitpod()

async def main():
    result = await client.environments.automations.upsert(
        environment_id="<environment-id>",
        automations_file={
            "services": {
                "database": {
                    "commands": {
                        "start": "docker run -p 5432:5432 postgres:16",
                        "ready": "pg_isready -h localhost",
                    },
                    "triggered_by": [{"postDevcontainerStart": {}}],
                }
            },
            "tasks": {
                "build": {
                    "command": "npm ci && npm run build",
                    "triggered_by": [{"postDevcontainerStart": {}}],
                }
            },
        },
    )
    print(f"Updated automations version: {result}")

asyncio.run(main())
```
```

--------------------------------

### Create Environment

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Creates a new Gitpod environment. This method accepts various parameters to configure the new environment.

```APIDOC
## POST /gitpod.v1.EnvironmentService/CreateEnvironment

### Description
Creates a new Gitpod environment.

### Method
POST

### Endpoint
/gitpod.v1.EnvironmentService/CreateEnvironment

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating an environment.
```

--------------------------------

### Differentiate None from Missing Fields

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/README.md

Provides a Python code example demonstrating how to use `.model_fields_set` to distinguish between an API field that is explicitly `null` (resulting in `None` in Python) and a field that is entirely missing from the response.

```python
if response.my_field is None:
  if 'my_field' not in response.model_fields_set:
    print('Got json like {}, without a "my_field" key present at all.')
  else:
    print('Got json like {"my_field": null}.')
```

--------------------------------

### Automatic and Manual Pagination for Environments

Source: https://context7.com/gitpod-io/gitpod-sdk-python/llms.txt

Illustrates both automatic iteration over all pages of environments and manual control using cursors and page metadata. Useful for handling large datasets.

```python
import asyncio
from gitpod import AsyncGitpod

client = AsyncGitpod()

async def main():
    # Automatic: iterates all pages transparently
    async for env in client.environments.list():
        print(env.id)

    # Manual: inspect page metadata
    page = await client.environments.list(pagination={"page_size": 10})
    print(f"Next cursor: {page.pagination.next_token if page.pagination else 'none'}")
    for env in page.environments:
        print(f"  {env.id}")

    if page.has_next_page():
        next_page = await page.get_next_page()
        print(f"Next page has {len(next_page.environments)} items")

asyncio.run(main())
```

--------------------------------

### Create Prebuild

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Creates a new prebuild for the workspace. This operation is asynchronous.

```APIDOC
## POST /gitpod.v1.PrebuildService/CreatePrebuild

### Description
Creates a new prebuild for the workspace.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/CreatePrebuild

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating a prebuild.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **PrebuildCreateResponse** (object) - Details of the created prebuild.

### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Async Gitpod API Usage with aiohttp

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/README.md

Instantiate the asynchronous Gitpod client using DefaultAioHttpClient for the HTTP backend and make a call to get the authenticated identity. The bearer token is read from the GITPOD_API_KEY environment variable by default.

```python
import os
import asyncio
from gitpod import DefaultAioHttpClient
from gitpod import AsyncGitpod


async def main() -> None:
    async with AsyncGitpod(
        bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
        http_client=DefaultAioHttpClient(),
    ) as client:
        response = await client.identity.get_authenticated_identity()
        print(response.organization_id)


asyncio.run(main())
```

--------------------------------

### Create Project

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Use this method to create a new Gitpod project. It requires project creation parameters.

```python
client.projects.create(**params) -> ProjectCreateResponse
```

--------------------------------

### Bulk Create Projects

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Creates multiple Gitpod projects simultaneously. Requires bulk creation parameters.

```python
client.projects.bulk_create(**params) -> ProjectBulkCreateResponse
```

--------------------------------

### Retrieve Prebuild

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Retrieves the details of a specific prebuild.

```APIDOC
## POST /gitpod.v1.PrebuildService/GetPrebuild

### Description
Retrieves the details of a specific prebuild.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/GetPrebuild

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for retrieving a prebuild.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **PrebuildRetrieveResponse** (object) - Details of the retrieved prebuild.

### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Configure HTTP Client with Proxies and Transports

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/README.md

Customize the underlying `httpx` client by passing it during `Gitpod` client initialization. This allows for proxy configuration and custom transports. Alternatively, use `DefaultHttpxClient` for common configurations.

```python
import httpx
from gitpod import Gitpod, DefaultHttpxClient

client = Gitpod(
    # Or use the `GITPOD_BASE_URL` env var
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)
```

--------------------------------

### List Project Environment Classes

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Lists the environment classes for Gitpod projects.

```APIDOC
## POST /gitpod.v1.ProjectService/ListProjectEnvironmentClasses

### Description
Lists the environment classes for Gitpod projects.

### Method
POST

### Endpoint
/gitpod.v1.ProjectService/ListProjectEnvironmentClasses

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for listing project environment classes.

### Request Example
```json
{
  "params": { ... }
}
```

### Response
#### Success Response (200)
- **SyncProjectEnvironmentClassesPage[ProjectEnvironmentClass]** (object) - A page of project environment classes.
```

--------------------------------

### List Environments

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Lists all Gitpod environments accessible to the user, with optional filtering and pagination.

```APIDOC
## POST /gitpod.v1.EnvironmentService/ListEnvironments

### Description
Lists all Gitpod environments.

### Method
POST

### Endpoint
/gitpod.v1.EnvironmentService/ListEnvironments

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for listing environments.
```

--------------------------------

### Bulk Create Projects

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Creates multiple Gitpod projects in a single request.

```APIDOC
## POST /gitpod.v1.ProjectService/CreateProjects

### Description
Creates multiple Gitpod projects in a single request.

### Method
POST

### Endpoint
/gitpod.v1.ProjectService/CreateProjects

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for bulk creating projects.

### Request Example
```json
{
  "params": { ... }
}
```

### Response
#### Success Response (200)
- **ProjectBulkCreateResponse** (object) - Details of the bulk creation operation.
```

--------------------------------

### Create Prebuild Logs Token

Source: https://github.com/gitpod-io/gitpod-sdk-python/blob/main/api.md

Creates a token for accessing prebuild logs.

```APIDOC
## POST /gitpod.v1.PrebuildService/CreatePrebuildLogsToken

### Description
Creates a token for accessing prebuild logs.

### Method
POST

### Endpoint
/gitpod.v1.PrebuildService/CreatePrebuildLogsToken

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for creating a logs token.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **PrebuildCreateLogsTokenResponse** (object) - The generated logs token.

### Response Example
```json
{
  "example": "response body"
}
```
```