POST/v1/admin/change-sets/{id}/commit

Commit a previewed administration change set

operation ID: post_v1_admin_change_sets_by_id_commit

Overview

Commit a previewed 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 commit a previewed 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 POST \
  --url "$ORDINATE_URL/v1/admin/change-sets/00000000-0000-4000-8000-000000000001/commit" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Idempotency-Key: string" \
  --header "Content-Type: application/json" \
  --data '{
    "preview_hash": "string"
  }'

Expected output · 200

Immutable commit receipt

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 sends the smallest contract-derived body and asks OrdinateDB to commit a previewed administration change set. The documented 200 response is immutable commit receipt.

How it works

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

Reference

Required capability: model-edit
Authorization scope: handler-resolved target

Parameters

Name	In	Required	Type and constraints
`id`	path	yes	`string`format: uuid
`Idempotency-Key`	header	yes	`string`min length: 1 · max length: 255

Request body

application/json

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

unknown fields rejected

Example request body

{
  "preview_hash": "string"
}

Responses

200Immutable commit receipt

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, state conflict, name conflict, hash mismatch, or idempotency conflict

application/json

AdminChangeCommitConflict

one of

option 1

AdminChangeDriftConflict

codeany JSONrequired

correlation_idstringrequired

format: uuid

detailsobjectrequired

unknown fields rejected

currentobjectrequired

unknown fields rejected

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

unknown fields rejected

current_txstringrequired

Exact signed 64-bit integer encoded as a decimal string

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

unknown fields rejected

errorstringrequired

option 2

AdminChangeStateConflict

codeany JSONrequired

correlation_idstringrequired

format: uuid

detailsobjectrequired

unknown fields rejected

statestringrequired

unknown fields rejected

errorstringrequired

option 3

all of

option 1

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

option 2

must not match

codeany JSONrequired

Example 409 output

{
  "error": "string",
  "code": "conflict",
  "correlation_id": "00000000-0000-4000-8000-000000000001",
  "details": {
    "current_tx": "1785067200000000000",
    "current": {
      "resource_id": "00000000-0000-4000-8000-000000000001",
      "revision": "1785067200000000000",
      "name": "string",
      "path": "string"
    }
  }
}

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/commit`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Idempotency-Key": "string",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "preview_hash": "string"
})
});

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.

Commit a previewed administration change set

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics