Operations

Mutating environment endpoints return 202 Accepted with an operation record. Poll this endpoint until the operation reaches a terminal state.

Endpoint

GET /v1/operations/{operation_id}

Read an operation's current state.

Headers required: X-Scribase-Organization-ID: <org-id>

Response 200 OK:

JSON

{
  "id": "op-01J...",
  "kind": "create_environment",
  "state": "running",
  "organization_id": "acme",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:05Z",
  "result": null,
  "error": null
}

Operation states

State	Terminal	Description
`pending`	No	Queued, not yet started
`running`	No	In progress
`succeeded`	Yes	Completed successfully
`failed`	Yes	Completed with an error

Operation kinds

Kind	Triggered by
`create_environment`	`POST /v1/environments`
`delete_environment`	`DELETE .../environments/{env}`
`suspend_environment`	`POST .../environments/{env}/suspend`
`resume_environment`	`POST .../environments/{env}/resume`
`run_migrations`	`POST .../environments/{env}/migrations` with `apply: true`
`import`	`POST /v1/imports`

Polling

Terminal

scribase operation get acme op-01J...

Poll every few seconds until state is succeeded or failed. The SDK's operations.wait() handles polling automatically:

TypeScript

const { operation } = await scribase.environments.create({ ... });
const result = await scribase.operations.wait(operation.id, 'acme');

Error details

When state is failed, the error field carries a human-readable reason:

JSON

{
  "id": "op_01J...",
  "kind": "create_environment",
  "state": "failed",
  "attempt_count": 3,
  "error": "provider rejected the environment: region us-east is at capacity"
}

Errors returned by the request itself (as opposed to a failed operation) use the Problem Details format described in the API overview.

CLI

Terminal

scribase operation get acme op-01J...