Skip to main content

​
Create Environment

POST /v1/environments
Creates a new environment.

​
Request Body

FieldTypeRequiredDescription
namestringYesMachine-friendly name. Must match ^[a-z0-9_-]+$ (lowercase alphanumeric, hyphens, underscores)
display_namestringNoHuman-friendly display name
descriptionstringNoDescription of the environment
colorstringNoHex color code for the UI (defaults to #6366f1)
is_defaultbooleanNoWhether this is the default environment (defaults to false)

​
Response

Returns the created environment object. 
curl -X POST https://api.knoxcall.com/v1/environments \
  -H "Authorization: Bearer tk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging",
    "display_name": "Staging",
    "description": "Pre-production testing",
    "color": "#f59e0b"
  }'

import requests

resp = requests.post(
    "https://api.knoxcall.com/v1/environments",
    headers={
        "Authorization": "Bearer tk_live_abc123...",
        "Content-Type": "application/json"
    },
    json={
        "name": "staging",
        "display_name": "Staging",
        "description": "Pre-production testing",
        "color": "#f59e0b"
    }
)
environment = resp.json()

const resp = await fetch("https://api.knoxcall.com/v1/environments", {
  method: "POST",
  headers: {
    Authorization: "Bearer tk_live_abc123...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "staging",
    display_name: "Staging",
    description: "Pre-production testing",
    color: "#f59e0b"
  })
});
const environment = await resp.json();

​
Errors

StatusTypeDescription
400validation_errorInvalid name format or missing required field
403plan_limitEnvironments not available on your plan, or environment limit reached
409conflictAn environment with this name already exists