The Environments API from Terminal Use — 4 operation(s) for environments.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/terminal-use:terminal-use-environments-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Sb0 Environments API
version: 0.1.0
tags:
- name: Environments
paths:
/agents/{namespace_slug}/{agent_name}/environments:
get:
description: 'List all environments for an agent.
Environments define deployment targets (e.g., production, staging, preview).'
operationId: agents_environments_list
parameters:
- in: path
name: namespace_slug
required: true
schema:
title: Namespace Slug
type: string
- in: path
name: agent_name
required: true
schema:
title: Agent Name
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EnvListResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: List Environments
tags:
- Environments
x-fern-sdk-group-name:
- agents
- environments
x-fern-sdk-method-name: list
post:
description: 'Create a new environment for an agent.
Environments define deployment targets with branch matching rules.
The is_prod flag cannot be set via API - production environment is protected.
**Branch Rules:**
- Exact match: ["main"] or ["develop"]
- Wildcard: ["feature/*"] matches feature/foo, feature/bar
- Catch-all: ["*"] matches any branch'
operationId: agents_environments_create
parameters:
- in: path
name: namespace_slug
required: true
schema:
title: Namespace Slug
type: string
- in: path
name: agent_name
required: true
schema:
title: Agent Name
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnvRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/EnvResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Create Environment
tags:
- Environments
x-fern-sdk-group-name:
- agents
- environments
x-fern-sdk-method-name: create
/agents/{namespace_slug}/{agent_name}/environments/{env_name}:
delete:
description: 'Delete an environment.
**Note:** Production environments (is_prod=True) cannot be deleted.'
operationId: agents_environments_delete
parameters:
- in: path
name: namespace_slug
required: true
schema:
title: Namespace Slug
type: string
- in: path
name: agent_name
required: true
schema:
title: Agent Name
type: string
- in: path
name: env_name
required: true
schema:
title: Env Name
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteEnvResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Delete Environment
tags:
- Environments
x-fern-sdk-group-name:
- agents
- environments
x-fern-sdk-method-name: delete
get:
description: Get environment details by name.
operationId: agents_environments_retrieve
parameters:
- in: path
name: namespace_slug
required: true
schema:
title: Namespace Slug
type: string
- in: path
name: agent_name
required: true
schema:
title: Agent Name
type: string
- in: path
name: env_name
required: true
schema:
title: Env Name
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EnvResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get Environment
tags:
- Environments
x-fern-sdk-group-name:
- agents
- environments
x-fern-sdk-method-name: retrieve
put:
description: 'Update an existing environment.
All fields are optional - only provided fields will be updated.
**Production Environment Constraints:**
- branch_rules must be exactly one literal string (no wildcards)
- is_prod cannot be changed via API'
operationId: agents_environments_update
parameters:
- in: path
name: namespace_slug
required: true
schema:
title: Namespace Slug
type: string
- in: path
name: agent_name
required: true
schema:
title: Agent Name
type: string
- in: path
name: env_name
required: true
schema:
title: Env Name
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEnvRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EnvResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Update Environment
tags:
- Environments
x-fern-sdk-group-name:
- agents
- environments
x-fern-sdk-method-name: update
/agents/{namespace_slug}/{agent_name}/environments/{env_name}/branches:
get:
description: 'List all branches that match this environment''s branch rules.
For wildcard environments (like preview with ["*"]),
returns all non-retired branches for the agent.
For specific branch rules (like production with ["main"]),
returns only the matching branch(es).
Branches are sorted by updated_at descending (most recent first).'
operationId: agents_environments_branches_list
parameters:
- in: path
name: namespace_slug
required: true
schema:
title: Namespace Slug
type: string
- in: path
name: agent_name
required: true
schema:
title: Agent Name
type: string
- in: path
name: env_name
required: true
schema:
title: Env Name
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BranchListResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: List Branches for Environment
tags:
- Environments
x-fern-sdk-group-name:
- agents
- environments
- branches
x-fern-sdk-method-name: list
/agents/{namespace_slug}/{agent_name}/resolve-env:
get:
description: 'Resolve which environment matches a given branch.
Uses specificity-based matching:
- Exact match wins over wildcards (e.g., "main" matches production before preview)
- Prefix wildcards match by length (e.g., "feature/*" beats "*")
- Catch-all "*" has lowest priority
Returns 404 if no environment matches the branch.'
operationId: agents_resolve_env
parameters:
- in: path
name: namespace_slug
required: true
schema:
title: Namespace Slug
type: string
- in: path
name: agent_name
required: true
schema:
title: Agent Name
type: string
- in: query
name: branch
required: true
schema:
title: Branch
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ResolveEnvResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Resolve Environment for Branch
tags:
- Environments
x-fern-sdk-group-name:
- agents
- environments
x-fern-sdk-method-name: resolve_env
components:
schemas:
EnvListResponse:
description: Response for listing environments.
properties:
environments:
description: List of environments
items:
$ref: '#/components/schemas/EnvResponse'
title: Environments
type: array
total:
description: Total count
title: Total
type: integer
required:
- environments
- total
title: EnvListResponse
type: object
BranchListResponse:
description: Response for listing branches.
properties:
branches:
description: List of branches
items:
$ref: '#/components/schemas/BranchResponse'
title: Branches
type: array
total:
description: Total count
title: Total
type: integer
required:
- branches
- total
title: BranchListResponse
type: object
VersionStatus:
description: Status of a version in its lifecycle.
enum:
- DEPLOYING
- ACTIVE
- FAILED
- UNHEALTHY
- DRAINING
- RETIRED
- ROLLED_BACK
title: VersionStatus
type: string
BranchResponse:
description: Full branch details including current version.
properties:
agent_id:
description: Parent agent ID
title: Agent Id
type: string
created_at:
anyOf:
- format: date-time
type: string
- type: 'null'
description: Creation timestamp
title: Created At
current_version:
anyOf:
- $ref: '#/components/schemas/VersionSummary'
- type: 'null'
description: Currently active version (includes status)
git_branch:
description: Original git branch name
title: Git Branch
type: string
git_branch_normalized:
description: DNS-safe branch name
title: Git Branch Normalized
type: string
id:
description: Branch ID
title: Id
type: string
replicas:
description: Desired replica count
title: Replicas
type: integer
retired_at:
anyOf:
- format: date-time
type: string
- type: 'null'
description: When branch was retired
title: Retired At
retired_reason:
anyOf:
- type: string
- type: 'null'
description: Reason for retirement
title: Retired Reason
updated_at:
anyOf:
- format: date-time
type: string
- type: 'null'
description: Last update timestamp
title: Updated At
required:
- id
- agent_id
- git_branch
- git_branch_normalized
- replicas
title: BranchResponse
type: object
UpdateEnvRequest:
description: Request to update an environment (partial update).
properties:
branch_rules:
anyOf:
- items:
type: string
minItems: 1
type: array
- type: 'null'
description: Branch patterns for matching
title: Branch Rules
title: UpdateEnvRequest
type: object
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
title: Location
type: array
msg:
title: Message
type: string
type:
title: Error Type
type: string
required:
- loc
- msg
- type
title: ValidationError
type: object
CreateEnvRequest:
description: Request to create a new environment.
properties:
branch_rules:
description: Branch patterns for matching (e.g., ['feature/*'], ['develop'])
items:
type: string
minItems: 1
title: Branch Rules
type: array
name:
description: Environment name (lowercase alphanumeric and hyphens only)
maxLength: 100
minLength: 1
pattern: ^[a-z0-9-]+$
title: Name
type: string
required:
- name
- branch_rules
title: CreateEnvRequest
type: object
DeleteEnvResponse:
description: Response after deleting an environment.
properties:
deleted:
description: Whether the environment was deleted
title: Deleted
type: boolean
name:
description: The name of the deleted environment
title: Name
type: string
required:
- deleted
- name
title: DeleteEnvResponse
type: object
VersionSummary:
description: Abbreviated version info for embedding in branch responses.
properties:
deployed_at:
description: When this version was deployed
format: date-time
title: Deployed At
type: string
git_hash:
description: Git commit hash
title: Git Hash
type: string
git_message:
default: ''
description: Git commit message
title: Git Message
type: string
id:
description: Version ID
title: Id
type: string
source_filesystem_id:
anyOf:
- type: string
- type: 'null'
description: Filesystem snapshot that can reopen this version in Agent Builder
title: Source Filesystem Id
status:
$ref: '#/components/schemas/VersionStatus'
description: Version lifecycle status
required:
- id
- git_hash
- status
- deployed_at
title: VersionSummary
type: object
EnvResponse:
description: Full environment details.
properties:
agent_id:
description: Parent agent ID
title: Agent Id
type: string
branch_rules:
description: Branch patterns for matching (e.g., ['main'], ['feature/*'])
items:
type: string
title: Branch Rules
type: array
created_at:
anyOf:
- format: date-time
type: string
- type: 'null'
description: Creation timestamp
title: Created At
id:
description: Unique identifier
title: Id
type: string
is_prod:
description: Whether this is the production environment (protected)
title: Is Prod
type: boolean
name:
description: Environment name (e.g., 'production', 'staging')
title: Name
type: string
updated_at:
anyOf:
- format: date-time
type: string
- type: 'null'
description: Last update timestamp
title: Updated At
required:
- id
- agent_id
- name
- branch_rules
- is_prod
title: EnvResponse
type: object
ResolveEnvResponse:
description: Response for resolving which environment matches a branch.
properties:
branch:
description: The branch that was resolved
title: Branch
type: string
environment:
$ref: '#/components/schemas/EnvResponse'
description: The environment that matches the branch
required:
- environment
- branch
title: ResolveEnvResponse
type: object
x-fern-idempotency-headers:
- header: Idempotency-Key
name: idempotency_key
x-provenance:
method: harvested
publisher: Terminal Use
source: https://docs.terminaluse.com/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)