Operations related to 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/gitlab-ci-environments-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
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: GitLab access_requests Environments API
version: v4
description: Operations related to access requests
servers:
- url: https://gitlab.com
tags:
- name: environments
description: Operations related to environments
paths:
/api/v4/projects/{id}/environments:
get:
summary: List environments
description: Get all environments for a given project. This feature was introduced in GitLab 8.11.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
required: true
schema:
type: string
- in: query
name: page
description: Current page number
required: false
example: 1
schema:
type: integer
format: int32
default: 1
- in: query
name: per_page
description: Number of items per page
required: false
example: 20
schema:
type: integer
format: int32
default: 20
- in: query
name: name
description: Return the environment with this name. Mutually exclusive with search
required: false
schema:
type: string
- in: query
name: search
description: Return list of environments matching the search criteria. Mutually exclusive with name. Must be at least 3 characters.
required: false
schema:
type: string
- in: query
name: states
description: 'List all environments that match a specific state. Accepted values: `available`, `stopping`, or `stopped`. If no state value given, returns all environments'
required: false
schema:
type: string
enum:
- stopped
- stopping
- available
responses:
'200':
description: List environments
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/API_Entities_Environment'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- environments
operationId: getApiV4ProjectsIdEnvironments
post:
summary: Create a new environment
description: Creates a new environment with the given name and `external_url`. It returns `201` if the environment was successfully created, `400` for wrong parameters. This feature was introduced in GitLab 8.11.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
required: true
schema:
type: string
responses:
'201':
description: Create a new environment
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Environment'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Not found
tags:
- environments
operationId: postApiV4ProjectsIdEnvironments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postApiV4ProjectsIdEnvironments'
required: true
/api/v4/projects/{id}/environments/{environment_id}:
put:
summary: Update an existing environment
description: Updates an existing environment name and/or `external_url`. It returns `200` if the environment was successfully updated. In case of an error, a status code `400` is returned. This feature was introduced in GitLab 8.11.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
required: true
schema:
type: string
- in: path
name: environment_id
description: The ID of the environment
required: true
schema:
type: integer
format: int32
responses:
'200':
description: Update an existing environment
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Environment'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Not found
tags:
- environments
operationId: putApiV4ProjectsIdEnvironmentsEnvironmentId
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/putApiV4ProjectsIdEnvironmentsEnvironmentId'
required: true
delete:
summary: Delete an environment
description: It returns 204 if the environment was successfully deleted, and 404 if the environment does not exist. This feature was introduced in GitLab 8.11.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
required: true
schema:
type: string
- in: path
name: environment_id
description: The ID of the environment
required: true
schema:
type: integer
format: int32
responses:
'401':
description: Unauthorized
'204':
description: Delete an environment
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Environment'
'404':
description: Not found
tags:
- environments
operationId: deleteApiV4ProjectsIdEnvironmentsEnvironmentId
get:
description: Get a specific environment
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
required: true
schema:
type: string
- in: path
name: environment_id
description: The ID of the environment
required: true
schema:
type: integer
format: int32
responses:
'200':
description: Get a specific environment
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Environment'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- environments
operationId: getApiV4ProjectsIdEnvironmentsEnvironmentId
/api/v4/projects/{id}/environments/review_apps:
delete:
summary: Delete multiple stopped review apps
description: It schedules for deletion multiple environments that have already been stopped and are in the review app folder. The actual deletion is performed after 1 week from the time of execution. By default, it only deletes environments 30 days or older. You can change this default using the `before` parameter.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
required: true
schema:
type: string
- in: query
name: before
description: The date before which environments can be deleted. Defaults to 30 days ago. Expected in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`)
required: false
schema:
type: string
format: date-time
default: {}
- in: query
name: limit
description: Maximum number of environments to delete. Defaults to 100
required: false
schema:
type: integer
format: int32
default: 100
maximum: 1000
minimum: 1
- in: query
name: dry_run
description: Defaults to true for safety reasons. It performs a dry run where no actual deletion will be performed. Set to false to actually delete the environment
required: false
schema:
type: boolean
default: true
responses:
'400':
description: Bad request
'204':
description: Delete multiple stopped review apps
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_EnvironmentBasic'
'401':
description: Unauthorized
'404':
description: Not found
'409':
description: Conflict
tags:
- environments
operationId: deleteApiV4ProjectsIdEnvironmentsReviewApps
/api/v4/projects/{id}/environments/{environment_id}/stop:
post:
summary: Stop an environment
description: It returns 200 if the environment was successfully stopped.
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
required: true
schema:
type: string
- in: path
name: environment_id
description: The ID of the environment
required: true
schema:
type: integer
format: int32
responses:
'201':
description: Stop an environment
content:
application/json:
schema:
$ref: '#/components/schemas/API_Entities_Environment'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Not found
tags:
- environments
operationId: postApiV4ProjectsIdEnvironmentsEnvironmentIdStop
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postApiV4ProjectsIdEnvironmentsEnvironmentIdStop'
required: true
/api/v4/projects/{id}/environments/stop_stale:
post:
summary: Stop stale environments
description: It returns `200` if stale environment check was scheduled successfully
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project owned by the authenticated user
required: true
schema:
type: string
responses:
'201':
description: Stop stale environments
'400':
description: Bad request
'401':
description: Unauthorized
tags:
- environments
operationId: postApiV4ProjectsIdEnvironmentsStopStale
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/postApiV4ProjectsIdEnvironmentsStopStale'
required: true
components:
schemas:
API_Entities_Deployment:
type: object
properties:
id:
type: integer
format: int32
example: 41
iid:
type: integer
format: int32
example: 1
ref:
type: string
example: main
sha:
type: string
example: 99d03678b90d914dbb1b109132516d71a4a03ea8
created_at:
type: string
format: date-time
example: '2016-08-11T11:32:35.444Z'
updated_at:
type: string
format: date-time
example: '2016-08-11T11:32:35.444Z'
user:
$ref: '#/components/schemas/API_Entities_UserBasic'
environment:
$ref: '#/components/schemas/API_Entities_EnvironmentBasic'
deployable:
$ref: '#/components/schemas/API_Entities_Ci_Job'
status:
type: string
example: created
required:
- id
- iid
- ref
- sha
- created_at
- updated_at
- user
- environment
- deployable
- status
description: API_Entities_Deployment model
API_Entities_Ci_Job:
type: object
properties:
id:
type: integer
format: int32
example: 1
status:
type: string
example: waiting_for_resource
stage:
type: string
example: deploy
name:
type: string
example: deploy_to_production
ref:
type: string
example: main
tag:
type: boolean
coverage:
type: number
format: float
example: 98.29
allow_failure:
type: boolean
created_at:
type: string
format: date-time
example: '2015-12-24T15:51:21.880Z'
started_at:
type: string
format: date-time
example: '2015-12-24T17:54:30.733Z'
finished_at:
type: string
format: date-time
example: '2015-12-24T17:54:31.198Z'
erased_at:
type: string
format: date-time
example: '2015-12-24T18:00:29.728Z'
duration:
type: number
format: float
example: 0.465
description: Time spent running
queued_duration:
type: number
format: float
example: 0.123
description: Time spent enqueued
user:
$ref: '#/components/schemas/API_Entities_User'
commit:
$ref: '#/components/schemas/API_Entities_Commit'
pipeline:
$ref: '#/components/schemas/API_Entities_Ci_PipelineBasic'
failure_reason:
type: string
example: script_failure
web_url:
type: string
example: https://example.com/foo/bar/-/jobs/1
project:
type: object
properties:
ci_job_token_scope_enabled:
type: string
example: false
required:
- ci_job_token_scope_enabled
artifacts_file:
$ref: '#/components/schemas/API_Entities_Ci_JobArtifactFile'
artifacts:
type: array
items:
$ref: '#/components/schemas/API_Entities_Ci_JobArtifact'
runner:
$ref: '#/components/schemas/API_Entities_Ci_Runner'
runner_manager:
$ref: '#/components/schemas/API_Entities_Ci_RunnerManager'
artifacts_expire_at:
type: string
format: date-time
example: '2016-01-19T09:05:50.355Z'
archived:
type: boolean
example: false
tag_list:
type: array
items:
type: string
example:
- ubuntu18
- docker runner
required:
- id
- status
- stage
- name
- ref
- tag
- coverage
- allow_failure
- created_at
- started_at
- finished_at
- erased_at
- duration
- queued_duration
- user
- commit
- pipeline
- web_url
- project
- artifacts
- runner
- artifacts_expire_at
- archived
- tag_list
description: API_Entities_Ci_Job model
postApiV4ProjectsIdEnvironmentsEnvironmentIdStop:
type: object
properties:
force:
type: boolean
description: Force environment to stop without executing `on_stop` actions
default: false
description: Stop an environment
putApiV4ProjectsIdEnvironmentsEnvironmentId:
type: object
properties:
external_url:
type: string
description: The new URL on which this deployment is viewable
tier:
type: string
description: The tier of the new environment. Allowed values are `production`, `staging`, `testing`, `development`, and `other`
enum:
- production
- staging
- testing
- development
- other
cluster_agent_id:
type: integer
format: int32
description: The ID of the Cluster Agent to associate with this environment
kubernetes_namespace:
type: string
description: The Kubernetes namespace to associate with this environment
flux_resource_path:
type: string
description: The Flux resource path to associate with this environment
description:
type: string
description: The description of the environment
auto_stop_setting:
type: string
description: The auto stop setting for the environment. Allowed values are `always` and `with_action`
enum:
- always
- with_action
description: Update an existing environment
API_Entities_UserBasic:
type: object
properties:
id:
type: integer
format: int32
example: 1
username:
type: string
example: admin
public_email:
type: string
example: john@example.com
name:
type: string
example: Administrator
state:
type: string
example: active
locked:
type: boolean
avatar_url:
type: string
example: https://gravatar.com/avatar/1
avatar_path:
type: string
example: /user/avatar/28/The-Big-Lebowski-400-400.png
custom_attributes:
type: array
items:
$ref: '#/components/schemas/API_Entities_CustomAttribute'
web_url:
type: string
example: https://gitlab.example.com/root
required:
- id
- username
- public_email
- name
- state
- locked
- avatar_url
- web_url
description: API_Entities_UserBasic model
API_Entities_EnvironmentBasic:
type: object
properties:
id:
type: integer
format: int32
example: 1
name:
type: string
example: deploy
slug:
type: string
example: deploy
external_url:
type: string
example: https://deploy.gitlab.example.com
created_at:
type: string
format: date-time
example: '2019-05-25T18:55:13.252Z'
updated_at:
type: string
format: date-time
example: '2019-05-25T18:55:13.252Z'
required:
- id
- name
- slug
- external_url
- created_at
- updated_at
description: API_Entities_EnvironmentBasic model
API_Entities_LicenseBasic:
type: object
properties:
key:
type: string
example: gpl-3.0
name:
type: string
example: GNU General Public License v3.0
nickname:
type: string
example: GNU GPLv3
html_url:
type: string
example: http://choosealicense.com/licenses/gpl-3.0
source_url:
type: string
required:
- key
- name
- nickname
- html_url
- source_url
API_Entities_Environment:
type: object
properties:
id:
type: integer
format: int32
example: 1
name:
type: string
example: deploy
slug:
type: string
example: deploy
external_url:
type: string
example: https://deploy.gitlab.example.com
created_at:
type: string
format: date-time
example: '2019-05-25T18:55:13.252Z'
updated_at:
type: string
format: date-time
example: '2019-05-25T18:55:13.252Z'
tier:
type: string
example: development
project:
$ref: '#/components/schemas/API_Entities_BasicProjectDetails'
last_deployment:
$ref: '#/components/schemas/API_Entities_Deployment'
state:
type: string
example: available
auto_stop_at:
type: string
format: date-time
example: '2019-05-25T18:55:13.252Z'
cluster_agent:
$ref: '#/components/schemas/API_Entities_Clusters_Agent'
kubernetes_namespace:
type: string
flux_resource_path:
type: string
description:
type: string
example: description
auto_stop_setting:
type: string
example: always
required:
- id
- name
- slug
- external_url
- created_at
- updated_at
- tier
- project
- state
- auto_stop_at
- description
- auto_stop_setting
description: API_Entities_Environment model
API_Entities_Ci_RunnerManager:
type: object
properties:
id:
type: integer
format: int32
example: 8
system_id:
type: string
example: runner-1
version:
type: string
example: 16.11.0
revision:
type: string
example: 91a27b2a
platform:
type: string
example: linux
architecture:
type: string
example: amd64
created_at:
type: string
example: '2023-10-24T01:27:06.549Z'
contacted_at:
type: string
example: '2023-10-24T01:27:06.549Z'
ip_address:
type: string
example: 127.0.0.1
status:
type: string
example: online
job_execution_status:
type: string
enum:
- active
- idle
example: idle
required:
- id
- system_id
- version
- revision
- platform
- architecture
- created_at
- contacted_at
- ip_address
- status
- job_execution_status
description: API_Entities_Ci_RunnerManager model
API_Entities_Ci_JobArtifact:
type: object
properties:
file_type:
type: string
enum:
- archive
- metadata
- trace
- junit
- sast
- dependency_scanning
- container_scanning
- dast
- codequality
- license_scanning
- performance
- metrics
- metrics_referee
- network_referee
- lsif
- dotenv
- cobertura
- terraform
- accessibility
- cluster_applications
- secret_detection
- requirements
- coverage_fuzzing
- browser_performance
- load_performance
- api_fuzzing
- cluster_image_scanning
- cyclonedx
- requirements_v2
- annotations
- repository_xray
- jacoco
- scip
- sarif
- environment_key
example: archive
size:
type: integer
format: int32
example: 1000
filename:
type: string
example: artifacts.zip
file_format:
type: string
enum:
- raw
- zip
- gzip
example: zip
required:
- file_type
- size
- filename
- file_format
API_Entities_Ci_PipelineBasic:
type: object
properties:
id:
type: integer
format: int32
example: 1
iid:
type: integer
format: int32
example: 2
project_id:
type: integer
format: int32
example: 3
sha:
type: string
example: 0ec9e58fdfca6cdd6652c083c9edb53abc0bad52
ref:
type: string
example: feature-branch
status:
type: string
example: success
source:
type: string
example: push
created_at:
type: string
format: date-time
example: '2022-10-21T16:49:48.000+02:00'
updated_at:
type: string
format: date-time
example: '2022-10-21T16:49:48.000+02:00'
web_url:
type: string
example: https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61
required:
- id
- iid
- project_id
- sha
- ref
- status
- source
- created_at
- updated_at
- web_url
description: API_Entities_Ci_PipelineBasic model
API_Entities_Clusters_Agent:
type: object
properties:
id:
type: string
name:
type: string
config_project:
$ref: '#/components/schemas/API_Entities_ProjectIdentity'
created_at:
type: string
created_by_user_id:
type: string
is_receptive:
type: string
required:
- id
- name
- config_project
- created_at
- created_by_user_id
- is_receptive
description: API_Entities_Clusters_Agent model
API_Entities_BasicProjectDetails:
type: object
properties:
id:
type: integer
format: int32
example: 1
description:
type: string
example: desc
name:
type: string
example: project1
name_with_namespace:
type: string
example: John Doe / project1
path:
type: string
example: project1
path_with_namespace:
type: string
example: namespace1/project1
created_at:
type: string
format: date-time
example: '2020-05-07T04:27:17.016Z'
default_branch:
type: string
example: main
tag_list:
type: array
items:
type: string
example:
- tag
topics:
type: array
items:
type: string
example:
- topic
ssh_url_to_repo:
type: string
example: git@gitlab.example.com:gitlab/gitlab.git
http_url_to_repo:
type: string
example: https://gitlab.example.com/gitlab/gitlab.git
web_url:
type: string
example: https://gitlab.example.com/gitlab/gitlab
readme_url:
type: string
example: https://gitlab.example.com/gitlab/gitlab/blob/master/README.md
forks_count:
type: integer
format: int32
example: 1
license_url:
type: string
example: https://gitlab.example.com/gitlab/gitlab/blob/master/LICENCE
license:
$ref: '#/components/schemas/API_Entities_LicenseBasic'
avatar_url:
type: string
example: http://example.com/uploads/project/avatar/3/uploads/avatar.png
star_count:
type: integer
format: int32
example: 1
last_activity_at:
type: string
format: date-time
example: '2013-09-30T13:46:02Z'
visibility:
type: string
example: public
namespace:
$ref: '#/components/schemas/API_Entities_NamespaceBasic'
custom_attributes:
$ref: '#/components/schemas/API_Entities_CustomAttribute'
repository_storage:
type: string
example: default
required:
- id
- description
- name
- name_with_namespace
- path
- path_with_namespace
- created_at
- tag_list
- topics
- ssh_url_to_repo
- http_url_to_repo
- web_url
- avatar_url
- star_count
- last_activity_at
- visibility
- namespace
description: API_Entities_BasicProjectDetails model
API_Entities_NamespaceBasic:
type: object
properties:
id:
type: integer
format: int32
example: 2
name:
type: string
example: project
path:
type: string
example: my_project
kind:
type: string
example: project
full_path:
type: string
example: group/my_project
parent_id:
type: integer
format: int32
example: 1
avatar_url:
type: string
example: https://example.com/avatar/12345
web_url:
type: string
example: https://example.com/group/my_project
required:
- id
- name
- path
- kind
- full_path
- parent_id
- avatar_url
- web_url
API_Entities_Ci_Runner:
type: object
properties:
id:
type: integer
format: int32
example: 8
description:
type: string
example: test-1-20150125
ip_address:
type: string
example: 127.0.0.1
active:
type: boolean
example: true
paused:
type: boolean
example: false
is_shared:
type: boolean
example: true
runner_type:
type: string
enum:
- instance_type
- group_type
- project_type
example: instance_type
name:
type: string
example: test
online:
type: boolean
example: true
created_by:
$ref: '#/components/schemas/API_Entities_UserBasic'
created_at:
type: string
format: date-time
example: '2025-05-03T00:00:00.000Z'
status:
type: string
example: online
job_execution_status:
type: string
enum:
- active
- idle
example: idle
required:
- id
- description
- ip_address
- active
- paused
- is_shared
- runner_type
- name
- online
- created_at
- status
- job_execution_status
description: API_Entities_Ci_Runner model
API_Entities_Ci_JobArtifactFile:
type: object
properties:
filename:
type: string
example: artifacts.zip
size:
type: integer
format: int32
example: 1000
required:
- filename
- size
API_Entities_ProjectIdentity:
type: object
properties:
id:
type: integer
format: int32
example: 1
description:
type: string
example: desc
name:
type: string
example: project1
name_with_namespace:
type: string
example: John Doe / project1
path:
type: string
example: project1
path_with_namespace:
type: string
example: namespace1/project1
created_at:
type: string
format: date-time
example: '2020-05-07T04:27:17.016Z'
required:
- id
- description
- name
- name_with_namespace
- path
- path_with_namespace
- created_at
API_Entities_CustomAttribute:
type: object
properties:
key:
type: string
example: foo
value:
type: string
example: bar
required:
- key
- value
description: API_Entities_CustomAttribute model
API_Entities_User:
type: object
properties:
id:
type: integer
format: int32
example: 1
username:
type: string
example: admin
public_email:
type: string
example: john@example.com
name:
type: string
example: Administrator
state:
type: string
example: active
locked:
type: boolean
avatar_url:
type: string
example: https://gravatar.com/avatar/1
avatar_path:
type: string
example: /user/avatar/28/The-Big-Lebowski-400-400.png
custom_attributes:
type: array
items:
$ref: '#/components/schemas/API_Entities_CustomAttribute'
web_url:
type: string
example: https://gitlab.example.com/root
created_at:
type: string
bio:
type: string
location:
type: string
linkedin:
type: string
twitter:
type: string
discord:
type: string
website_url:
ty
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitlab-ci/refs/heads/main/openapi/gitlab-ci-environments-api-openapi.yml