> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt > Use this file to discover all available pages before exploring further. # Create environment > Creates a new environment in the current app. The env starts in the no-pin state — promote (POST `/v1/environments/{id}/promote`) is the only path to pin a version. Synchronously provisions a per-env Fly app; failure rolls back the env row and surfaces 500 `env_fly_provisioning_failed`. Per FR-028 no API key is auto-minted; the response includes `api_key_creation_url` for the post-create CTA. ## OpenAPI ````yaml /openapi.yaml post /v1/environments openapi: 3.0.3 info: contact: email: hello@agentmark.co url: https://docs.agentmark.co description: >- The AgentMark Gateway API lets you ingest traces, create scores, and retrieve prompt templates programmatically. Most developers should use the [AgentMark SDK](/introduction/overview) for integration. The REST API is for cases where you need direct HTTP access or are building a custom integration. Versioning: every endpoint is prefixed with `/v1/`. Breaking changes ship under a new version prefix (`/v2/`, etc.) with a 90-day-minimum deprecation window — see [API versioning & stability](/api-reference/versioning) for the full policy on what constitutes a breaking vs. additive change. title: AgentMark Gateway API version: '1.0' servers: - description: Production (AgentMark Cloud) url: https://api.agentmark.co - description: Local dev server (`npx @agentmark-ai/cli dev`) url: http://localhost:9418 security: - AppId: [] BearerAuth: [] tags: - description: Ingest, query, and export OpenTelemetry trace data. name: Traces - description: >- Coding-agent session ingest (outerlayer sync) and content-addressed session images. name: Agents - description: Query individual spans across traces. name: Spans - description: Create, retrieve, list, and delete score records for spans and traces. name: Scoring - description: Structured-filter search across observability resources. name: Search - description: Retrieve the effective synced project configuration. name: Config - description: List and retrieve datasets. name: Datasets - description: Query server feature availability. name: Capabilities - description: Per-model LLM pricing data. Public, unauthenticated. name: Pricing - description: >- Create, list, and revoke tenant API keys. Plaintext returned exactly once at creation. name: API Keys - description: >- List and retrieve score configuration definitions from the synced project config. name: Score Configs - description: >- Trigger and inspect managed deployments. POST returns 202; deployments run asynchronously and progress is observed via GET. name: Deployments - description: >- Per-app named environments (e.g. `dev`, `prod`). CRUD for env lifecycle; promote/rollback routes land alongside in this group as feature 054 lands the saga. name: Environments - description: >- App CRUD — the top-level tenant entity every other resource hangs off. Lets a headless agent provision an app without the dashboard. name: Apps - description: Service health checks. name: Health paths: /v1/environments: post: tags: - Environments summary: Create environment description: >- Creates a new environment in the current app. The env starts in the no-pin state — promote (POST `/v1/environments/{id}/promote`) is the only path to pin a version. Synchronously provisions a per-env Fly app; failure rolls back the env row and surfaces 500 `env_fly_provisioning_failed`. Per FR-028 no API key is auto-minted; the response includes `api_key_creation_url` for the post-create CTA. operationId: create-environment requestBody: content: application/json: schema: properties: name: type: string required: - name type: object responses: '201': content: application/json: schema: properties: data: properties: api_key_creation_url: type: string created_at: type: string created_by_id: nullable: true type: string current_commit_sha: nullable: true type: string current_version: minimum: 0 type: integer epoch: type: integer fly_app_name: nullable: true type: string id: format: uuid type: string is_default: type: boolean is_ephemeral: type: boolean latest_deployment_id: format: uuid nullable: true type: string machine_status: enum: - active - cleaned_up - none type: string name: type: string source_pr_number: nullable: true type: integer required: - id - name - is_default - current_version - latest_deployment_id - current_commit_sha - fly_app_name - machine_status - is_ephemeral - source_pr_number - epoch - created_at - created_by_id - api_key_creation_url type: object required: - data type: object description: Environment created and Fly app provisioned. '400': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Invalid request body or env name. '401': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Missing or invalid API key. '402': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: >- App has reached the environment limit for its tier ('env_limit_exceeded'). '403': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Caller lacks 'environment.insert' permission. '409': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Env name already exists on this app. '500': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Fly app provisioning failed. components: securitySchemes: AppId: description: >- Application ID for tenant scoping. X-Outerlayer-App-Id is accepted as an equivalent header. in: header name: X-Agentmark-App-Id type: apiKey BearerAuth: description: API key (sk_agentmark_*) scheme: bearer type: http ````