Manage environments — the primitive that workspaces are created from. Variables, files, skills, MCPs, warm-hooks, and warm-pools are all scoped to an environment. Every organization has a singleton Global environment whose values apply to every workspace. Personal environments are scoped to the authenticated user and can be standalone or source-backed by a team environment.
openapi: 3.1.0
info:
title: Replica Analytics Environments API
version: 2.0.0
description: The Replica API allows you to programmatically manage cloud workspaces for AI agents. Use this API to manage environments (the org-scoped primitive workspaces are created from — including variables, files, skills, MCPs, warm hooks, start hooks, and warm pools), create and manage replicas, send messages, manage chats, stream events, read connected repositories and repository sets, and configure automations.
servers:
- url: https://api.tryreplicas.com
description: Production API
security:
- apiKey: []
tags:
- name: Environments
description: Manage environments — the primitive that workspaces are created from. Variables, files, skills, MCPs, warm-hooks, and warm-pools are all scoped to an environment. Every organization has a singleton Global environment whose values apply to every workspace. Personal environments are scoped to the authenticated user and can be standalone or source-backed by a team environment.
paths:
/v1/environments:
get:
operationId: listEnvironments
summary: List Environments
description: Returns environments visible to the caller, including the singleton Global environment for org scope. Each record includes counts of attached variables, files, skills, and MCPs.
tags:
- Environments
parameters:
- name: scope
in: query
required: false
description: Filter by environment scope. `org` returns team environments, `user` returns your personal environments, `all` returns both. Defaults to `org`.
schema:
type: string
enum:
- org
- user
- all
default: org
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListEnvironmentsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
post:
operationId: createEnvironment
summary: Create Environment
description: Creates a new team or personal environment. `repository_id` and `repository_set_id` are mutually exclusive; both may be omitted for an unbound environment that can back repo-less workspaces. Personal environments are visible only to the authenticated user. When `scope=user` and `source_environment_id` references a team environment, the personal environment inherits from that source instead of copying it.
tags:
- Environments
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvironmentRequest'
responses:
'201':
description: Environment created
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
description: An environment with this name already exists
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{id}:
get:
operationId: getEnvironment
summary: Get Environment
description: Returns a single environment. Pass the literal string `global` for the org's singleton Global environment (auto-created on first access — no need to look up its UUID first).
tags:
- Environments
parameters:
- name: id
in: path
required: true
description: Environment UUID, or the literal string `global` for the org's Global environment.
schema:
type: string
example: global
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
patch:
operationId: updateEnvironment
summary: Update Environment
description: Updates a non-global environment. Only provided fields are changed. `PATCH /v1/environments/global` returns 400 with a pointer to the nested resource endpoints (variables, files, skills, MCPs, warm hooks) — the Global env's metadata cannot be edited directly. Source-backed personal environments cannot change `repository_id`, `repository_set_id`, or `system_prompt`, but may set `personal_preferences`, instructions appended after the inherited system prompt. Returns 409 when an automation still references the environment in a way that blocks the requested change.
tags:
- Environments
parameters:
- name: id
in: path
required: true
description: Environment UUID. The literal `global` is rejected with 400 — see endpoint description.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEnvironmentRequest'
responses:
'200':
description: Environment updated
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
operationId: deleteEnvironment
summary: Delete Environment
description: Deletes an environment. Returns 409 when an automation still references the environment, when personal environments inherit from it, or when called against the Global environment (which cannot be deleted).
tags:
- Environments
parameters:
- name: id
in: path
required: true
description: Environment UUID. The literal `global` is rejected with 409 — the Global env cannot be deleted.
schema:
type: string
responses:
'200':
description: Environment deleted
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/variables:
get:
operationId: listEnvironmentVariables
summary: List Environment Variables
description: Returns every variable attached to the environment. Values are returned in plaintext (they are encrypted at rest, decrypted on read).
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global` for the org's Global environment.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListEnvironmentVariablesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
post:
operationId: createEnvironmentVariable
summary: Create Environment Variable
description: 'Adds a new variable to the environment. Values are encrypted at rest. The `(environment, key)` pair must be unique within the org. Source-backed personal environments can override inherited variable keys only when the inherited variable has `personal_override_allowed: true`.'
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global` for the org's Global environment.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvironmentVariableRequest'
responses:
'201':
description: Variable created
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentVariableResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Admin access required to change personal override policy
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/variables/{id}:
patch:
operationId: updateEnvironmentVariable
summary: Update Environment Variable
description: 'Updates a variable. Only provided fields are changed. Source-backed personal environments can override inherited variable keys only when the inherited variable has `personal_override_allowed: true`.'
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
- name: id
in: path
required: true
description: Variable UUID
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEnvironmentVariableRequest'
responses:
'200':
description: Variable updated
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentVariableResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Admin access required to change personal override policy
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
operationId: deleteEnvironmentVariable
summary: Delete Environment Variable
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
- name: id
in: path
required: true
description: Variable UUID
schema:
type: string
format: uuid
responses:
'200':
description: Variable deleted
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/files:
get:
operationId: listEnvironmentFiles
summary: List Environment Files
description: Returns every file attached to the environment. Files are dropped into the workspace at the configured `path` when the workspace is provisioned.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListEnvironmentFilesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
post:
operationId: createEnvironmentFile
summary: Create Environment File
description: Adds a new file to the environment. Maximum content size is 64 KB (65,536 bytes). The `path` is validated against allowed locations (typically under `~/`).
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvironmentFileRequest'
responses:
'201':
description: File created
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentFileResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/files/{id}:
patch:
operationId: updateEnvironmentFile
summary: Update Environment File
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
- name: id
in: path
required: true
description: File UUID
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEnvironmentFileRequest'
responses:
'200':
description: File updated
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentFileResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
operationId: deleteEnvironmentFile
summary: Delete Environment File
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
- name: id
in: path
required: true
description: File UUID
schema:
type: string
format: uuid
responses:
'200':
description: File deleted
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/skills:
get:
operationId: listEnvironmentSkills
summary: List Environment Skills
description: Returns every skill enabled on the environment. Skills come from [skills.sh](https://skills.sh) and are installed into workspaces created from the environment.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListEnvironmentSkillsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
post:
operationId: createEnvironmentSkill
summary: Enable Environment Skill
description: Enables a skill on the environment. Use [GET /v1/environment-skills/search](#tag/Environments/operation/searchEnvironmentSkills) to discover skills first, then enable them with this endpoint. Returns 409 if the skill (by `slug` or `source`) is already enabled on the environment.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvironmentSkillRequest'
responses:
'201':
description: Skill enabled
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentSkillResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/skills/{id}:
delete:
operationId: deleteEnvironmentSkill
summary: Disable Environment Skill
description: Disables a previously enabled skill on the environment.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
- name: id
in: path
required: true
description: Environment skill UUID (the membership row, not the skill catalog slug).
schema:
type: string
format: uuid
responses:
'200':
description: Skill disabled
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/skills-registries:
get:
operationId: listEnvironmentSkillsRegistries
summary: List Skill Registries
description: Returns every skill registry configured on the environment, along with the discovered skills from each registry repository.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListEnvironmentSkillsRegistriesResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
post:
operationId: createEnvironmentSkillsRegistry
summary: Add Skill Registry
description: Adds a GitHub repository as a skill registry on the environment. Skills discovered in the repository are installed into workspaces at provisioning time.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: GitHub repository URL (e.g. https://github.com/org/skills-repo).
required:
- url
responses:
'200':
description: Registry created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvironmentSkillsRegistryResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/skills-registries/{skillsRegistryId}:
delete:
operationId: deleteEnvironmentSkillsRegistry
summary: Remove Skill Registry
description: Removes a skill registry from the environment.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
- name: skillsRegistryId
in: path
required: true
description: Skills registry UUID.
schema:
type: string
format: uuid
responses:
'200':
description: Registry removed
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/repo-skills:
get:
operationId: listRepoSkills
summary: List Skills From Bound Repo
description: 'Returns skills, agents, commands, prompts, and rule files committed to the repository (or repository set) the environment is bound to. Resolved live from the repo''s default branch via GitHub. Read-only: these are sourced from the user''s git tree, not from `skills.sh`. When the environment is not bound to a repo, returns an empty list with no error.'
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
responses:
'200':
description: Successful response. `error` is populated when discovery encountered a partial failure (e.g. the repo has no GitHub App installation); the UI surfaces it inline rather than treating it as a 5xx.
content:
application/json:
schema:
$ref: '#/components/schemas/ListRepoSkillsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/mcps:
get:
operationId: listEnvironmentMcps
summary: List Environment MCPs
description: Returns every MCP (Model Context Protocol server) attached to the environment.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ListEnvironmentMcpsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
post:
operationId: createEnvironmentMcp
summary: Create Environment MCP
description: 'Adds a new MCP server to the environment. `name` must match `^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$` and cannot start with reserved prefix `replicas-`. The `config` shape depends on the `transport`: stdio uses `{ command, args, env }`; http and sse use `{ url, headers }`.'
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvironmentMcpRequest'
responses:
'201':
description: MCP created
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentMcpResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/mcps/{id}:
patch:
operationId: updateEnvironmentMcp
summary: Update Environment MCP
description: Updates an MCP. Only provided fields are changed. When changing `transport`, `config` is required and must match the new transport's shape.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
- name: id
in: path
required: true
description: MCP UUID
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEnvironmentMcpRequest'
responses:
'200':
description: MCP updated
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentMcpResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/InternalServerError'
delete:
operationId: deleteEnvironmentMcp
summary: Delete Environment MCP
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
- name: id
in: path
required: true
description: MCP UUID
schema:
type: string
format: uuid
responses:
'200':
description: MCP deleted
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/warm-hooks:
get:
operationId: getEnvironmentWarmHooks
summary: Get Warm Hooks State
description: Returns the active warm hook (if any) and warm pool config (if any) for the environment, along with current pool counts.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/GetWarmHooksResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/warm-hooks/save:
post:
operationId: saveEnvironmentWarmHook
summary: Save Warm Hook
description: Persists and activates the supplied script as the warm hook for the environment without running a test. Use this when you want to save quickly without waiting for a sandbox to spin up.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SaveWarmHookRequest'
responses:
'201':
description: Warm hook saved and activated
content:
application/json:
schema:
$ref: '#/components/schemas/SaveWarmHookResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/environments/{environmentId}/warm-hooks/save-test:
post:
operationId: saveAndTestEnvironmentWarmHook
summary: Save and Test Warm Hook
description: Saves the supplied script as the active warm hook for the environment and runs it in an isolated sandbox. Always persists the new version; the response includes the test result so callers can decide whether to roll back. The endpoint takes 30–90 seconds to return because it spins up a real sandbox.
tags:
- Environments
parameters:
- name: environmentId
in: path
required: true
description: Environment UUID, or the literal string `global`.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SaveAndTestWarmHookRequest'
responses:
'201':
description: Warm hook saved (test result included in body)
content:
application/json:
schema:
$ref: '#/components/schemas/SaveAndTestWarmHookResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthor
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/replicas/refs/heads/main/openapi/replicas-environments-api-openapi.yml