---
title: "Get Environment"
method: GET
path: "/v1/environments/{id}"
tags: ["v1"]
---

# Get Environment

`GET /v1/environments/{id}`

## Request

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

Return one saved environment, by id or by name.

## Path parameters

- `id` string, required

## Headers

- `user-agent` string, nullable

## Response `200`

Successful Response

- EnvironmentResponse: One saved environment.
  - `environment` Environment, required: A saved environment: the machine agents run in (repositories, variables, MCP servers, image, compute, hooks), defined once and referenced by name or id from agents and session starts.
    - `created_at` string, date-time, required: When the environment was created.
    - `edited_by` GithubAccountSnippet: Sometimes the GitHub API returns a user of github (can include bots) using this snippet instead of the full GithubAccount model. One example, is when the API returns a pull request. This is the least amount of info we need to represent a GitHub account.
      - `avatar_url` string, required
      - `id` integer, required
      - `login` string, required
      - `name` string, nullable, required
      - `type` 'User' | 'Organization' | 'Bot' | 'Mannequin', required
    - `environment` EnvironmentDocumentOutput, required: A parsed environment document: identity plus the environment body. The body fields are flattened to the top level of the file (not nested under an `environment:` key) — the file *is* the environment, so nesting would be ceremony. `to_environment()` projects the body for substitution into an agent.
      - `compute` ComputeConfigOutput: Environment compute sizing. Every field is optional; an omitted field inherits the platform default (2 vCPU / 4096 MiB / 3600s). A resolved value outside the platform bounds fails validation loudly (a sync error on the config) rather than being clamped silently. `memory` and `timeout` each accept a shorthand string ("8GB", "30m") or an explicit units object ({gb: 8}, {minutes: 30}); the `memory_mib` / `timeout_seconds` properties resolve either form to the canonical integer the environment is sized with. `timeout` is the max wall-clock the agent may run in one environment before it is stopped, capped at 1h (equal to the default, so today the knob only shortens a session; the cap matches the 1-hour validity of the session's GitHub token). Compute currently uses a temporary flat one-cent amount each time an environment is started for a session, subject to the account's existing free-compute exemptions.
        - `cpu` integer, nullable, required
        - `memory` union, required
          - string
          - MemorySizeOutput: A memory size as explicit units, summed (binary: 1GB = 1024MB = 1024MiB). Set any of `gb`/`mb` (at least one). The alternative to the `8GB`-style shorthand string.
            - `gb` integer, nullable, required
            - `mb` integer, nullable, required
        - `timeout` union, required
          - string
          - DurationOutput: A duration as explicit units, summed. Set any of `hours`/`minutes`/ `seconds` (at least one). The alternative to the `30m`-style shorthand string wherever a duration is accepted.
            - `hours` integer, nullable, required
            - `minutes` integer, nullable, required
            - `seconds` integer, nullable, required
      - `ellipsis` EnvironmentIdentityOutput, required: The Ellipsis namespace of an environment file. `kind: environment` is what routes a synced YAML here instead of to the agent parser, which requires `kind: agent`.
        - `description` string, nullable
        - `kind` 'environment', required
        - `metadata` ConfigMetadataOutput
          - `annotations` object, required
          - `labels` string[], required
        - `name` string, nullable
      - `hooks` EnvironmentHooksOutput: Environment lifecycle scripts, in order: build_base, after_checkout, before_start, validate. The first two produce reusable snapshots; before_start runs before an agent starts or resumes its session, and validate runs last to check that the environment has what the agent needs. Scripts run as the environment's user in the workspace directory `/sandbox`. A nonzero exit fails the session. Legacy post_start/post_clone scripts remain supported for existing configs; both run after workspace preparation, before the agent starts or resumes. They cannot be combined with the new lifecycle fields.
        - `after_checkout` union, required: Prepare the requested source revision after Ellipsis checks out all repositories, before saving the prepared environment. Skipped when that prepared environment is reused.
          - EnvironmentScript: An inline shell script run as the environment's user, with the workspace directory `/sandbox` as cwd.
            - `run` string, required: Shell script to run in the workspace directory `/sandbox`.
          - string
        - `before_start` union, required: Run before the agent starts or resumes a session, after the environment is ready. This hook is not cached and adds to session startup time.
          - EnvironmentScript: An inline shell script run as the environment's user, with the workspace directory `/sandbox` as cwd.
            - `run` string, required: Shell script to run in the workspace directory `/sandbox`.
          - string
        - `build_base` union, required: Build a reusable environment before full checkout. Cached by declared inputs, script, toolchain, resources, and build configuration. A string is shorthand for run with all repositories as inputs.
          - EnvironmentBaseBuildOutput: Create a reusable base, optionally using only selected repository files.
            - `inputs` string[], nullable, required: Exact files relative to the workspace directory `/sandbox`, including the repository name. Only these files are available during build_base and their contents and modes determine reuse. Omit to use all repositories and invalidate on any source change; [] means no repository files.
            - `run` string, required: Shell script to run in the workspace directory `/sandbox`.
          - string
        - `post_clone` string, nullable, required: Legacy session startup script. Use before_start for session setup or after_checkout for cached source preparation.
        - `post_start` string, nullable, required: Legacy session startup script. Use before_start in new configurations.
        - `validate` union, required: Check that the environment works, for example that required tools are on PATH. Runs last, after before_start, each time a session starts or resumes and each time the environment is built after a change. A nonzero exit fails the session or the build. Not cached.
          - EnvironmentScript: An inline shell script run as the environment's user, with the workspace directory `/sandbox` as cwd.
            - `run` string, required: Shell script to run in the workspace directory `/sandbox`.
          - string
      - `mcp_servers` union[]
        - union
          - string
          - McpServerRef: One built-in MCP server this agent attaches by name (`linear`/`slack`). A name reference over the connected built-in set — the platform manages the server's transport and credentials. A session gets a built-in server only when its config names it here or the session started from that server's own surface. For a server the platform does not provide, define it instead (`McpStdioServer` / `McpRemoteServer`).
            - `name` string, required
          - McpStdioServerOutput: A bring-your-own stdio MCP server: the harness spawns `command` inside the environment and speaks JSON-RPC over its stdin/stdout. The command must be runnable in the environment image — install its runtime via `hooks.build_base` / `hooks.after_checkout` if the managed environment lacks it. `env` values may embed `${NAME}` references, resolved at run time from the account's secrets store (see `mcp_secret_refs`); everything else is passed literally.
            - `args` string[], required
            - `command` string, required
            - `env` object, required
            - `name` string, required
          - McpRemoteServerOutput: A bring-your-own remote MCP server: the harness talks HTTP to `url`. Nothing runs in the environment image. `headers` carry static auth (e.g. `Authorization: Bearer ${TOKEN}`); values may embed `${NAME}` secret references, resolved at run time from the account's secrets store.
            - `headers` object, required
            - `name` string, required
            - `url` string, required
      - `repositories` RepositoryRefOutput[]
        - `name` string, required
        - `owner` string, nullable, required
        - `ref` string, nullable, required
      - `variables` EnvironmentVariableOutput[]
        - `name` string, required
        - `value` string, nullable, required
    - `id` string, required: Unique identifier of the environment.
    - `last_sync_error` string, nullable: The parse or validation error from the most recent sync attempt, or null when it succeeded. A non-null value means sessions run the last good definition, not the YAML currently on the branch.
    - `last_synced_commit_sha` string, nullable: The last commit the environment was synced from.
    - `managed_by` 'github' | 'api', required: Which writer owns an agent: the repository file it is defined in, or this API. Every agent has exactly one owner, fixed when it is created and changed only by linking or unlinking it.
    - `name` string, required: The environment's customer-unique addressable name; usable anywhere an environment is referenced, interchangeably with the id.
    - `raw_yaml` string, required: The environment's YAML: the file as written for environments defined in a repository, or the definition rendered as YAML for environments managed through the API. A failed sync keeps the last valid YAML.
    - `sha` string, required: The environment's content identity fingerprint.
    - `source_details` GithubSourceDetails: Identifies the file a GitHub-sourced agent is synced from. Identified by the repository ID (not owner/name) so repository and org renames don't orphan the config; resolve display names from gh_repositories at read time.
      - `branch` string, required
      - `path` string, required
      - `repo_id` integer, required
    - `updated_at` string, date-time, required: When the environment was last updated.

## Other responses

- `401`: The bearer token is missing, invalid, or revoked.
- `403`: The credential may not perform this action, or the account is blocked.
- `404`: No such environment in your account.
- `422`: Validation Error

---

[API](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api.md) - [All operations](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/revisions/344b16df9a1a?raw)