---
title: "Save a project environment"
method: POST
path: "/api/v1/{forge}/{project}/environments"
tags: ["Project Agents"]
---

# Save a project environment

`POST /api/v1/{forge}/{project}/environments`

## Request

- Base URL: `https://entire.io` (the document declares no server; this is the origin it was published from)
- URL: `https://entire.io/api/v1/{forge}/{project}/environments`
- Auth: none declared. Required headers: `Idempotency-Key`

Saving runs, schedules and dispatches nothing. Reuse the Idempotency-Key with the same body to retry; a changed body needs a new key.

## Path parameters

- `forge` 'gh' | 'et', required
- `project` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `name` string, required
  - `description` string
  - `auto_stop_minutes` integer, nullable

## Response `201`

Saved, or replayed from an earlier request with the same key

- object
  - `id` string, required
  - `project_id` string, required
  - `version` integer, required
  - `etag` string, required: Write token: send it unchanged as If-Match to replace or archive.
  - `created_at` string, required
  - `created_by` object, required
    - `kind` string, required
    - `id` string, required
  - `updated_at` string, required
  - `archived_at` string, nullable, required
  - `archived_by` object
    - `kind` string, required
    - `id` string, required
  - `name` string, required
  - `description` string, required
  - `provider` string
  - `auto_stop_minutes` integer, nullable, required

## Other responses

- `400`: Invalid request
- `401`: Not authenticated
- `403`: Feature disabled, or repository push is missing
- `404`: Project or resource not found
- `409`: Conflict: archived, in use, scope changed, or Idempotency-Key reused
- `413`: Request body too large
- `422`: Validation failed
- `502`: Agents service unavailable

## Changes

- **2026-10-26** `3ff783b497b2`: 1 breaking, 1 warning
  - the response property `provider` became optional for the status `201`
  - removed the request property `provider`
- **2026-10-23** `365f01543923`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/entire/apis/entire-api/changes/api/v1/:forge/:project/environments/post.md)

---

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