Environments

Environments provide isolated workspaces within an organization. Each environment has its own policies, API keys, and data. Common configurations include development, staging, and production.

List Environments

GET /v1/organizations/{org_id}/environments

Lists all environments in the organization. Requires membership in the organization.

Request:

curl https://api.hatidata.com/v1/organizations/org_a1b2c3d4/environments \
  -H "Authorization: Bearer <jwt>"

Response 200 OK:

{
  "data": [
    {
      "env_id": "env_prod_x1y2",
      "name": "production",
      "slug": "production",
      "org_id": "org_a1b2c3d4",
      "status": "active",
      "connection": {
        "host": "acme-corp.proxy.hatidata.com",
        "port": 5439,
        "database": "hatidata"
      },
      "settings": {
        "query_timeout_ms": 30000,
        "max_concurrent_queries": 100,
        "cache_enabled": true
      },
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-02-10T14:30:00Z"
    },
    {
      "env_id": "env_stg_a3b4",
      "name": "staging",
      "slug": "staging",
      "org_id": "org_a1b2c3d4",
      "status": "active",
      "connection": {
        "host": "acme-corp-staging.proxy.hatidata.com",
        "port": 5439,
        "database": "hatidata"
      },
      "settings": {
        "query_timeout_ms": 60000,
        "max_concurrent_queries": 50,
        "cache_enabled": false
      },
      "created_at": "2026-01-15T10:05:00Z",
      "updated_at": "2026-01-15T10:05:00Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false,
    "total": 2
  }
}

Create Environment

POST /v1/organizations/{org_id}/environments

Creates a new environment. Requires Owner or Admin role.

Request:

curl -X POST https://api.hatidata.com/v1/organizations/org_a1b2c3d4/environments \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "development",
    "slug": "development",
    "settings": {
      "query_timeout_ms": 120000,
      "max_concurrent_queries": 25,
      "cache_enabled": false
    }
  }'

Response 201 Created:

{
  "env_id": "env_dev_c5d6",
  "name": "development",
  "slug": "development",
  "org_id": "org_a1b2c3d4",
  "status": "provisioning",
  "connection": {
    "host": "acme-corp-development.proxy.hatidata.com",
    "port": 5439,
    "database": "hatidata"
  },
  "settings": {
    "query_timeout_ms": 120000,
    "max_concurrent_queries": 25,
    "cache_enabled": false
  },
  "created_at": "2026-02-16T10:00:00Z",
  "updated_at": "2026-02-16T10:00:00Z"
}

Field	Type	Required	Description
name	string	Yes	Display name
slug	string	Yes	URL-safe identifier (unique within org)
settings.query_timeout_ms	integer	No	Query timeout in milliseconds (default: 30000)
settings.max_concurrent_queries	integer	No	Max concurrent queries (default: 100)
settings.cache_enabled	boolean	No	Enable query caching (default: true)

Environment Status Values

Status	Description
provisioning	Infrastructure being deployed
active	Environment is ready for queries
suspended	Temporarily disabled
decommissioning	Being removed

Promote Environment

POST /v1/organizations/{org_id}/environments/{env_id}/promote

Promotes environment configuration (policies, masking rules, RLS filters) from one environment to another. Data is not copied. Requires Owner or Admin role.

Request:

curl -X POST https://api.hatidata.com/v1/organizations/org_a1b2c3d4/environments/env_stg_a3b4/promote \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "target_env_id": "env_prod_x1y2",
    "include": ["policies", "masking_rules", "rls_filters"],
    "dry_run": false
  }'

Response 200 OK:

{
  "promotion_id": "promo_e7f8g9",
  "source_env": "env_stg_a3b4",
  "target_env": "env_prod_x1y2",
  "status": "completed",
  "changes": {
    "policies_promoted": 5,
    "policies_updated": 2,
    "policies_created": 3,
    "masking_rules_promoted": 8,
    "rls_filters_promoted": 3
  },
  "promoted_by": "usr_x1y2z3",
  "promoted_at": "2026-02-16T11:00:00Z"
}

Field	Type	Required	Description
target_env_id	string	Yes	Destination environment
include	string[]	No	What to promote (default: all). Options: policies, masking_rules, rls_filters, abac_policies
dry_run	boolean	No	Preview changes without applying (default: false)

Dry Run

Set dry_run: true to preview what would change without modifying the target environment. The response includes the same changes object showing what would be applied.

Error Responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid settings or missing required fields
401	UNAUTHORIZED	Missing or invalid authentication
403	FORBIDDEN	Insufficient role (must be Owner or Admin)
404	NOT_FOUND	Organization or environment not found
409	CONFLICT	Slug already in use within the organization