GET/v1/admin/change-sets/{id}

Read an administration change set

operation ID: get_v1_admin_change_sets_by_id

Overview

Read an administration change set. The administration API uses previewed change sets so operational changes can be inspected before they are made durable.

When to use it

Use it when an application needs to read an administration change set.
Use it when an operations tool needs a reviewable, controlled administration workflow.

Quick example

Set the base URL and replace generated identifiers or credentials with values from your installation.

cURL

curl --request GET \
  --url "$ORDINATE_URL/v1/admin/change-sets/00000000-0000-4000-8000-000000000001" \
  --header "Authorization: Bearer $ORDINATE_TOKEN"

Expected output · 200

Stored change set

Example 200 output

{
  "change_set_id": "00000000-0000-4000-8000-000000000001",
  "state": "preview",
  "reason": "string",
  "operations": [
    {
      "kind": "asset.rename",
      "asset_id": "00000000-0000-4000-8000-000000000001",
      "name": "string"
    }
  ],
  "preview": {
    "summary": "string",
    "changes": [
      {
        "resource_kind": "asset",
        "resource_id": "00000000-0000-4000-8000-000000000001",
        "base_tx": "1785067200000000000",
        "before": {
          "name": "string",
          "path": "string"
        },
        "after": {
          "name": "string",
          "path": "string"
        }
      }
    ],
    "warnings": [
      {
        "code": "string",
        "message": "string"
      }
    ]
  },
  "preview_hash": "string",
  "created_ns": "1785067200000000000",
  "committed_ns": "1785067200000000000",
  "principal": "string",
  "receipt": {
    "operation_id": "string",
    "model_tx": "1785067200000000000",
    "committed_operations": [
      {
        "kind": "asset.rename",
        "resource_kind": "asset",
        "resource_id": "00000000-0000-4000-8000-000000000001",
        "resulting_tx": "1785067200000000000"
      }
    ],
    "audit_events": [
      {
        "entity_kind": "asset",
        "entity_id": "00000000-0000-4000-8000-000000000001",
        "action": "rename"
      }
    ]
  }
}

The cURL request supplies the documented path and query values and asks OrdinateDB to read an administration change set. The documented 200 response is stored change set.

How it works

Create a preview first, retain its identifier, then read, commit, or cancel that same change set.

Reference

Required capability: initiator-or-admin
Authorization scope: change-set

Parameters

Name	In	Required	Type and constraints
`id`	path	yes	`string`format: uuid

Request body

This operation has no request body.

Responses

200Stored change set

application/json

change_set_idstringrequired

format: uuid

committed_nsany ofrequired

any of

option 1

string

Exact signed 64-bit integer encoded as a decimal string

pattern: ^-?[0-9]+$

option 2

null

created_nsstringrequired

Exact signed 64-bit integer encoded as a decimal string

pattern: ^-?[0-9]+$

operationsarrayrequired

min items: 1 · max items: 1

array · min 1 · max 1

asset_idstringrequired: format: uuid
kindstringrequired
namestringrequired

unknown fields rejected

previewobjectrequired

unknown fields rejected

changesarrayrequired

array

afterobjectrequired

unknown fields rejected

namestringrequired
pathstringrequired

unknown fields rejected

base_txstringrequired

Exact signed 64-bit integer encoded as a decimal string

pattern: ^-?[0-9]+$

beforeobjectrequired

unknown fields rejected

namestringrequired
pathstringrequired

unknown fields rejected

resource_idstringrequired

format: uuid

resource_kindstringrequired

unknown fields rejected

summarystringrequired

warningsarrayrequired

array

codestringrequired
messagestringrequired

unknown fields rejected

preview_hashstringrequired

pattern: ^[0-9a-f]{64}$

principalstringrequired

reasonstringrequired

receiptany ofrequired

any of

option 1

audit_eventsarrayrequired

array

actionstringrequired
entity_idstringrequired: format: uuid
entity_kindstringrequired

unknown fields rejected

committed_operationsarrayrequired

array

kindstringrequired
resource_idstringrequired: format: uuid
resource_kindstringrequired
resulting_txstringrequired: Exact signed 64-bit integer encoded as a decimal string
pattern: ^-?[0-9]+$

unknown fields rejected

model_txstringrequired

Exact signed 64-bit integer encoded as a decimal string

pattern: ^-?[0-9]+$

operation_idstringrequired

pattern: ^change:[0-9a-fA-F-]{36}$

unknown fields rejected

option 2

null

statestringrequired

unknown fields rejected

Example 200 output

{
  "change_set_id": "00000000-0000-4000-8000-000000000001",
  "state": "preview",
  "reason": "string",
  "operations": [
    {
      "kind": "asset.rename",
      "asset_id": "00000000-0000-4000-8000-000000000001",
      "name": "string"
    }
  ],
  "preview": {
    "summary": "string",
    "changes": [
      {
        "resource_kind": "asset",
        "resource_id": "00000000-0000-4000-8000-000000000001",
        "base_tx": "1785067200000000000",
        "before": {
          "name": "string",
          "path": "string"
        },
        "after": {
          "name": "string",
          "path": "string"
        }
      }
    ],
    "warnings": [
      {
        "code": "string",
        "message": "string"
      }
    ]
  },
  "preview_hash": "string",
  "created_ns": "1785067200000000000",
  "committed_ns": "1785067200000000000",
  "principal": "string",
  "receipt": {
    "operation_id": "string",
    "model_tx": "1785067200000000000",
    "committed_operations": [
      {
        "kind": "asset.rename",
        "resource_kind": "asset",
        "resource_id": "00000000-0000-4000-8000-000000000001",
        "resulting_tx": "1785067200000000000"
      }
    ],
    "audit_events": [
      {
        "entity_kind": "asset",
        "entity_id": "00000000-0000-4000-8000-000000000001",
        "action": "rename"
      }
    ]
  }
}

400Invalid request, UUID, operation, or idempotency key

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 400 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

401Authentication required

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 401 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

403Target capability or access is denied

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 403 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

404Change set or target not found

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 404 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

409Preview drift, name conflict, hash mismatch, or idempotency conflict

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 409 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

500Administration change-set storage failed

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 500 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

503Model database is not configured or unavailable

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 503 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

Code examples

These examples are generated from the source contract. Replace the base URL, credentials, identifiers, and minimal generated values for your instance.

JavaScript

const ordinateUrl = "http://localhost:8080";
const token = "<bearer-token>";

const response = await fetch(`${ordinateUrl}/v1/admin/change-sets/00000000-0000-4000-8000-000000000001`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`
  }
});

if (!response.ok) {
  throw new Error(`OrdinateDB returned ${response.status}: ${await response.text()}`);
}

const data = await response.json();
console.log(data);

Wire conventions — Understand the prerequisite concepts and transport behavior for this operation.
REST endpoint index — Find other operations in Administration.

Read an administration change set

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics