Instances

The developer clone lifecycle: launch, inspect, get credentials, reset, refresh, extend, and destroy. Every route on this page is bearer-scoped and, unless noted, owner-scoped — you only ever operate on your own instances (an admin actor is not special-cased here, except where noted).

See Getting started: developer for the linear walkthrough and Clone pools for how a launch can be fast-claimed instead of provisioned on demand.

The instance object

Every route below that returns an instance uses this shape:

{
  "id": "0ab2b1ab-bd4a-4e1a-9ab8-c3b0251ee37d",
  "owner_user": "3e6f0a2b-7c8d-4e1f-9a2b-3c4d5e6f7a8b",
  "golden": "prod-pg16",
  "golden_version": 3,
  "namespace": "ns-3e6f0a2b",
  "size": "medium",
  "ttl": "168h",
  "reset_generation": 0,
  "desired_state": "present",
  "phase": "Ready",
  "endpoint": "0ab2b1ab-bd4a-4e1a-9ab8-c3b0251ee37d-rw.ns-3e6f0a2b.svc:5432",
  "message": "",
  "created_at": "2026-07-18T21:03:12Z",
  "expires_at": "2026-07-25T21:03:12Z"
}

• phase mirrors the agent's observed state: Pending, Provisioning, Ready, Failed, or similar — the same vocabulary adj get prints.
• message carries the failure reason when phase is Failed; empty otherwise.
• expires_at is created_at + ttl, approximating when the data-plane TTL reaper destroys the instance; null if ttl doesn't parse as a duration.
• reset_generation increments on every adj reset — a cheap way to tell whether an instance has been reset since you last looked.

POST /v1/instances — launch (clone)

Request body

$ curl -s https://api.stagdb.com/v1/instances -X POST -H "Authorization: Bearer $TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{"golden":"prod-pg16","size":"medium","ttl":"168h"}'

Response 201 Created — an instance object (see above), typically with phase: "Pending" — poll GET /v1/instances/{id} (or use adj get --wait) until phase reaches Ready.

If a clone pool has a warm clone for this golden, the launch fast-claims it instead of triggering a fresh volume provision — same request, same response shape, just faster.

GET /v1/instances — list your instances

$ curl -s https://api.stagdb.com/v1/instances -H "Authorization: Bearer $TOKEN"

Response 200 OK

{"instances": [ /* instance objects, as above */ ]}

Non-admins see only their own instances; admins see every instance in the org.

GET /v1/instances/{id} — get one instance

$ curl -s https://api.stagdb.com/v1/instances/0ab2b1ab-bd4a-4e1a-9ab8-c3b0251ee37d -H "Authorization: Bearer $TOKEN"

Response 200 OK — a single instance object.

GET /v1/instances/{id}/credentials — get live credentials

Owner-only — even an admin JWT gets 403 reading another member's credentials; this is the one route where admin doesn't override ownership.

Credentials are brokered live through the data-plane agent on every call — nothing is cached or persisted in the control plane. The access itself is audited (instance.credentials.read) as metadata only; the secret value never appears in the audit trail.

$ curl -s https://api.stagdb.com/v1/instances/0ab2b1ab-bd4a-4e1a-9ab8-c3b0251ee37d/credentials \
    -H "Authorization: Bearer $TOKEN"

Response 200 OK

{
  "uri": "postgresql://app:s3cr3t-pw@0ab2b1ab-bd4a-4e1a-9ab8-c3b0251ee37d-rw.ns-3e6f0a2b.svc:5432/app",
  "host": "0ab2b1ab-bd4a-4e1a-9ab8-c3b0251ee37d-rw.ns-3e6f0a2b.svc",
  "port": 5432,
  "dbname": "app",
  "username": "app",
  "password": "s3cr3t-pw"
}

DELETE /v1/instances/{id} — destroy

$ curl -s https://api.stagdb.com/v1/instances/0ab2b1ab-bd4a-4e1a-9ab8-c3b0251ee37d -X DELETE \
    -H "Authorization: Bearer $TOKEN" -o /dev/null -w '%{http_code}\n'
202

Response: 202 Accepted, empty body — teardown proceeds asynchronously on the data plane. Poll GET /v1/instances/{id} (it will 404 once fully reaped) or watch adj get <id> --wait.

POST /v1/instances/{id}/reset — discard changes

Re-clones the instance from the same golden version it was already on — whatever the developer changed is discarded, but nothing about which version it tracks changes.

$ curl -s https://api.stagdb.com/v1/instances/0ab2b1ab-bd4a-4e1a-9ab8-c3b0251ee37d/reset -X POST \
    -H "Authorization: Bearer $TOKEN"

Response 200 OK — the updated instance object; reset_generation is incremented and phase typically returns to Pending/Provisioning while the re-clone happens.

POST /v1/instances/{id}/refresh — move to the latest version

Re-clones the instance onto the latest version of its golden (discarding changes, same as reset, but also advancing the version pin).

Request body

$ curl -s https://api.stagdb.com/v1/instances/0ab2b1ab-bd4a-4e1a-9ab8-c3b0251ee37d/refresh -X POST \
    -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'

Response 200 OK — the updated instance object, with golden_version bumped to whatever was latest at request time.

POST /v1/instances/{id}/extend — extend the TTL

Request body

$ curl -s https://api.stagdb.com/v1/instances/0ab2b1ab-bd4a-4e1a-9ab8-c3b0251ee37d/extend -X POST \
    -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"ttl":"336h"}'

Response 200 OK — the updated instance object with a later expires_at.

Next

• Quota — the 429 launch can return.
• Pools — the fast-claim path a launch may take instead of provisioning on demand.