OrdinateDB

Documentation

product Pre-releaseunwritten sections are marked
POST/v1/admin/change-sets/{id}/cancel

Cancel a previewed administration change set

operation ID: post_v1_admin_change_sets_by_id_cancel

Overview

Cancel 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 cancel 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/cancel" \
  --header "Authorization: Bearer $ORDINATE_TOKEN"

Expected output · 200

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

NameInRequiredType and constraints
idpathyes
stringformat: uuid

Request body

This operation has no request body.

Responses

200Cancelled 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
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/cancel`, {
  method: "POST",
  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);

Related topics