---
title: "POST /api/v1/organizations/{organization_id}/verify/environments"
method: POST
path: "/api/v1/organizations/{organization_id}/verify/environments"
tags: ["organizations"]
---

# POST /api/v1/organizations/{organization_id}/verify/environments

`POST /api/v1/organizations/{organization_id}/verify/environments`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/organizations/{organization_id}/verify/environments`
- Auth: HTTP bearer

## Path parameters

- `organization_id` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- union
  - object
    - `project_id` string: Project slug or public ID. When omitted, creates a separate project for this environment.
    - `repository_id` string, nullable
    - `slug` string, required
    - `name` string: Optional for a website target; defaults to its hostname. Required for a draft environment without a target URL.
    - `target_url` string, uri, required
    - `target_kind` 'production' | 'staging' | 'preview' | 'development' | 'custom'
    - `default_policy` object
    - `allowed_actions` 'read_only' | 'writes': read_only only looks around; writes may create, change and delete data. Defaults to read_only for production and writes otherwise.
    - `imessage_number` string, nullable: International destination number; blank or null clears it on an added environment.
    - `messaging_tester_number` string, nullable: One configured tester number. Copied to each preview; may be overridden locally before preparation.
  - object
    - `project_id` string: Project slug or public ID. When omitted, creates a separate project for this environment.
    - `repository_id` string, nullable
    - `slug` string, required
    - `name` string, required: Optional for a website target; defaults to its hostname. Required for a draft environment without a target URL.
    - `target_url` string, uri
    - `target_kind` 'production' | 'staging' | 'preview' | 'development' | 'custom'
    - `default_policy` object
    - `allowed_actions` 'read_only' | 'writes': read_only only looks around; writes may create, change and delete data. Defaults to read_only for production and writes otherwise.
    - `imessage_number` string, nullable: International destination number; blank or null clears it on an added environment.
    - `messaging_tester_number` string, nullable: One configured tester number. Copied to each preview; may be overridden locally before preparation.

## Response `200`

Existing environment returned for an idempotent replay

- VerifyEnvironment
  - `id` string, required
  - `organization_id` string, required
  - `project_id` string, nullable, required: Owning project. Null only for unassigned legacy environments.
  - `repository_id` string, nullable, required
  - `hosted_app_id` string, nullable, required
  - `active_revision_id` string, nullable, required
  - `verify_network_connection_id` string, nullable, required
  - `slug` string, required
  - `name` string, required
  - `status` string, required
  - `connection` 'managed' | 'external', required
  - `target_url` string, uri, nullable, required
  - `target_kind` string, nullable, required
  - `allowed_actions` 'read_only' | 'writes', required
  - `default_policy_json` object, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `imessage_number` string, nullable, required: International destination number; blank or null clears it on an added environment.
  - `lock_version` integer, required

## Other responses

- `201`: Verify environment created
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `422`: Unprocessable entity
- `502`: Bad gateway

---

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