---
title: "Update environment"
method: PATCH
path: "/v1/environments/{id}"
tags: ["Environments"]
---

# Update environment

`PATCH /v1/environments/{id}`

## Request

- Base URL: `https://api.replicas.dev`
- URL: `https://api.replicas.dev/v1/environments/{id}`
- Auth: HTTP bearer

Updates only the fields you send. Set `repository_ids` to `[]` to remove all repositories. `personal_preferences` can only be set on personal environments and is appended after the inherited system prompt.

## Path parameters

- `id` string, required

## Headers

- `X-Replicas-Api-Version` '2026-10-07'

## Request body

- UpdateEnvironmentRequest: Request body for updating an environment. Only provided fields are changed.
  - `name` string
  - `description` string, nullable
  - `repository_ids` string[]: Replaces the repositories this environment clones, in checkout order. An empty array removes all. Requires write access to the environment.
  - `system_prompt` string, nullable
  - `default_skills` DefaultSkills: Built-in skills installed in every workspace. Omitted abilities default to enabled.
    - `replicas_agent` object
      - `enabled` boolean
      - `abilities` object: Ability name to enabled flag.
  - `personal_preferences` string, nullable: Only settable on personal environments. Appended after the (inherited) system prompt.

## Response `200`

Environment updated

- EnvironmentResponse
  - `environment` Environment, required: The configuration a workspace starts with. An environment builds on its `source_environment_id` chain, starting at its root. Personal environments have `user_id` set and are visible only to their owner.
    - `id` string, uuid, required: Unique identifier
    - `organization_id` string, uuid, required: Owning organization
    - `user_id` string, uuid, nullable, required: Owning user for personal environments. Null for team environments.
    - `name` string, required: Human-readable name
    - `description` string, nullable, required: Optional description
    - `repository_ids` string[], required: Repositories workspaces in this environment clone, in checkout order. Inherited from the source environment when `inherit_repositories` is true. Empty = repo-less workspace.
    - `inherit_repositories` boolean, required: True when this environment uses its source environment's repositories.
    - `system_prompt` string, nullable, required: Optional system prompt prepended to every workspace's coding agent.
    - `personal_preferences` string, nullable, required: User-authored instructions appended after the (inherited) system prompt. Only settable on personal environments, and editable even on forks.
    - `source_environment_id` string, uuid, nullable, required: Parent environment this one forks; unset fields are inherited from it. Null for environments that are not forks.
    - `variable_count` integer: Number of variables attached to this environment
    - `file_count` integer: Number of files
    - `skill_count` integer: Number of enabled skills
    - `mcp_count` integer: Number of MCPs
    - `access` EnvironmentAccess: Effective permissions for the caller. Read allows discovery, full inspection, and selection for workspaces or automations. Write allows all mutations and implies Read.
      - `can_write` boolean, required
      - `can_read` boolean, required
    - `status` EnvironmentStatus: `ready`: new workspaces start with the current setup. `applying`: `changes` reach new workspaces after `apply_after` (`waiting`) or once the warm hook finishes (`running`); until then they start with the previous setup. `needs_attention`: the latest changes failed to apply, so new workspaces start with the setup that went live at `live_since`.
      - `state` 'ready' | 'applying' | 'needs_attention', required
      - `phase` 'waiting' | 'running' | 'idle' | 'null', nullable, required: `idle`: the environment is unused, so its saved changes build the next time someone starts or selects it
      - `apply_after` string, date-time, nullable, required
      - `live_since` string, date-time, nullable, required: When the setup new workspaces start with went live
      - `first_setup` boolean, required: True while applying an environment that has never been set up
      - `changes` EnvironmentChange[], required
        - `kind` 'repositories' | 'warm_hook' | 'variable' | 'file' | 'skill' | 'skills_registry' | 'default_skills' | 'agent_auth' | 'workspace_size' | 'agent_setup' | 'restore' | 'system', required
        - `key` string, nullable, required: The edited row: variable key, file path, skill slug, registry, or provider
        - `op` 'created' | 'updated' | 'deleted', required
        - `user_id` string, uuid, nullable, required: Who made the edit
      - `failure` object, nullable, required
        - `build_id` string, uuid, required
        - `kind` 'hook' | 'infra', required: `hook`: a warm hook failed; it is not retried until the next change or an explicit retry
        - `message` string, nullable, required
        - `failed_at` string, date-time, nullable, required
        - `run_id` string, uuid, nullable, required: The failed warm hook run; its full log is at `/v1/environments/{environment_id}/hook-runs/{run_id}`
        - `exit_code` integer, nullable, required
        - `cause` object, nullable, required: Likely cause, read from the log tail and exit code. Null for infrastructure failures.
          - `kind` 'timeout' | 'out_of_memory' | 'disk_full' | 'lockfile_mismatch' | 'missing_secret' | 'command_not_found' | 'network' | 'missing_file' | 'exit_code', required
          - `summary` string, required
          - `fix` string, required
          - `line` string, nullable, required: The log line the cause was read from
        - `log_tail` string[], required: Last lines of the log
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `400`: Bad request - Missing or invalid parameters
- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - The authenticated account cannot access this resource
- `404`: Resource not found
- `409`: Conflict - Resource already exists or operation conflicts with current state
- `500`: Internal server error

---

[API](https://skmtc.dev/replicas/apis/replicas-api.md) - [All operations](https://skmtc.dev/replicas/apis/replicas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/replicas/apis/replicas-api/revisions/2703ac1c9cb7?raw)