Environments

An environment is a Postgres database (and its associated application services) that Scribase provisions and manages. Each environment belongs to a project and has a kind, a data mode, and a lifecycle managed through the control-plane API.

Environment kinds

Data modes

Endpoints

POST /v1/environments

Create an environment. Returns 202 Accepted with an operation to poll.

Request body:

{
  "organization_id": "acme",
  "project_id": "store",
  "environment_id": "production",
  "kind": "production",
  "data_mode": "snapshot",
  "region": "us-east",
  "postgres_major": 17,
  "ttl_hours": null
}

ttl_hours is optional and only meaningful for preview environments. Set it to have the environment automatically deleted after N hours.

Response 202 Accepted:

{
  "id": "op_01J...",
  "kind": "create_environment",
  "environment": { "organization_id": "acme", "project_id": "store", "environment_id": "production" },
  "state": "pending",
  "attempt_count": 0
}

Headers required: Idempotency-Key

Example:

scribase env create acme store production production snapshot us-east create-prod-001
# Preview with 72-hour TTL
scribase env create acme store pr-42 preview sanitized us-east create-pr42-001 72

GET /v1/organizations/{org}/projects/{project}/environments/{env}

Read an environment record.

Response 200 OK:

{
  "organization_id": "acme",
  "project_id": "store",
  "environment_id": "production",
  "kind": "production",
  "data_mode": "snapshot",
  "region": "us-east",
  "phase": "ready",
  "postgres_major": 17
}

Preview environments also carry ttl_hours and expires_at_epoch_seconds. The connection string is not part of the record; read it from the connection endpoint below.

Example:

scribase env get acme store production

POST /v1/organizations/{org}/projects/{project}/environments/{env}/suspend

Suspends a running environment. Returns 202 Accepted.

Headers required: Idempotency-Key

scribase env suspend acme store production suspend-001

POST /v1/organizations/{org}/projects/{project}/environments/{env}/resume

Resumes a suspended environment. Returns 202 Accepted.

Headers required: Idempotency-Key

scribase env resume acme store production resume-001

DELETE /v1/organizations/{org}/projects/{project}/environments/{env}

Deletes an environment. Returns 202 Accepted. Deletion is permanent.

Headers required: Idempotency-Key

scribase env delete acme store production delete-001

POST /v1/organizations/{org}/projects/{project}/environments/{env}/renew

Extend a preview's lifetime to ttl_hours from now, without recreating it. Returns 200 OK with the renewed expiry.

curl -X POST "$SCRIBASE_API_URL/v1/organizations/acme/projects/store/environments/pr-42/renew" \
  -H "Authorization: Bearer $SCRIBASE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ttl_hours": 48}'

ttl_hours must be a positive integer; 0 is rejected with invalid_ttl.

GET /v1/organizations/{org}/projects/{project}/environments/{env}/connection

Returns the environment's Postgres connection URI as {"connection_uri": "postgresql://..."}. This is a server-to-server endpoint: keep the URI out of browsers and logs.

GET /v1/organizations/{org}/projects/{project}/environments/{env}/usage

The environment's flat-price usage envelope: the plan, its flat price, the billing period, each hard cap with current use, and any capacity packs.

Environment lifecycle

phase moves through:

requested → provisioning → ready ⟷ suspended
                 ↓            ↓
        failed_recoverable  updating → ready
                              ↓
                          deleting → deleted

All state transitions are asynchronous. Poll the operation returned by each mutating call until state is succeeded, failed, or cancelled.

Listing

GET /v1/environments lists an organization's environments as {"environments": [...]}.