GET/v1/operations/{namespaced_id}

Read a permission-filtered operation

operation ID: get_v1_operations_by_namespaced_id

Overview

Read a permission-filtered operation. Operations are permission-filtered records for server-managed work that may outlive one HTTP request.

When to use it

Use it when an application needs to read a permission-filtered operation.
Use it when an operator needs to list or inspect the progress and outcome of asynchronous work.

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/operations/change%3A00000000-0000-4000-8000-000000000001" \
  --header "Authorization: Bearer $ORDINATE_TOKEN"

Expected output · 200

Operation

Example 200 output

{
  "id": "string",
  "kind": "string",
  "principal": "string",
  "reason": "string",
  "source_change_set_id": "00000000-0000-4000-8000-000000000001",
  "state": "queued",
  "stage": "string",
  "progress": {
    "completed": 0,
    "total": 0,
    "unit": "string"
  },
  "rate": 0,
  "estimated_work_remaining": 0,
  "affected_resources": [
    {
      "kind": "string",
      "id": "string"
    }
  ],
  "cancellable": false,
  "created_ns": "1785067200000000000",
  "completed_ns": "1785067200000000000",
  "detail": {
    "adapter": "change-set",
    "change_set_id": "00000000-0000-4000-8000-000000000001",
    "change_set_state": "preview"
  },
  "receipt": {
    "adapter": "change-set",
    "value": {
      "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"
        }
      ]
    }
  },
  "error": {}
}

The cURL request supplies the documented path and query values and asks OrdinateDB to read a permission-filtered operation. The documented 200 response is operation.

How it works

The namespaced identifier selects one operation record while list results are filtered to work the caller may inspect.

Reference

Required capability: authenticated
Authorization scope: owner-or-admin

Parameters

Name	In	Required	Type and constraints
`namespaced_id`	path	yes	`string`pattern: ^change:[0-9a-fA-F-]{36}$

Request body

This operation has no request body.

Responses

200Operation

application/json

affected_resourcesarrayrequired

array

idstringrequired
kindstringrequired

unknown fields rejected

cancellablebooleanrequired

completed_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]+$

detailone ofrequired

Adapter-specific identity and native state. New adapters add discriminated variants without changing the common operation fields.

one of

option 1

adapterstringrequired
change_set_idstringrequired: format: uuid
change_set_statestringrequired

unknown fields rejected

errorany ofrequired

any of

option 1

any of

option 1

object with arbitrary properties

option 2

array

any items

option 3

string

option 4

number

option 5

integer

option 6

boolean

option 7

null

option 2

null

estimated_work_remainingany ofrequired

any of

option 1

integerformat: int64 · minimum: 0

option 2

null

idstringrequired

Stable adapter-namespaced operation ID

pattern: ^[a-z][a-z0-9.-]*:.+$

kindstringrequired

pattern: ^[a-z][a-z0-9.-]*(?:\.[a-z0-9.-]+)+$

principalstringrequired

progressobjectrequired

unknown fields rejected

completedintegerrequired: format: int64 · minimum: 0
totalany ofrequired: any of
option 1
integerformat: int64 · minimum: 0
option 2
null
unitstringrequired

unknown fields rejected

rateany ofrequired

any of

option 1

number

option 2

null

reasonstringrequired

receiptany ofrequired

any of

option 1

one of

option 1

adapterstringrequired

valueobjectrequired

unknown fields rejected

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

source_change_set_idstringrequired

Required provenance link to the durable change set that initiated this operation

format: uuid

stagestringrequired

statestringrequired

unknown fields rejected

Example 200 output

{
  "id": "string",
  "kind": "string",
  "principal": "string",
  "reason": "string",
  "source_change_set_id": "00000000-0000-4000-8000-000000000001",
  "state": "queued",
  "stage": "string",
  "progress": {
    "completed": 0,
    "total": 0,
    "unit": "string"
  },
  "rate": 0,
  "estimated_work_remaining": 0,
  "affected_resources": [
    {
      "kind": "string",
      "id": "string"
    }
  ],
  "cancellable": false,
  "created_ns": "1785067200000000000",
  "completed_ns": "1785067200000000000",
  "detail": {
    "adapter": "change-set",
    "change_set_id": "00000000-0000-4000-8000-000000000001",
    "change_set_state": "preview"
  },
  "receipt": {
    "adapter": "change-set",
    "value": {
      "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"
        }
      ]
    }
  },
  "error": {}
}

400Invalid query, cursor, limit, namespace, or operation ID

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"
}

404Operation not found or not visible to this principal

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"
}

500Operations catalogue 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/operations/change%3A00000000-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 Operations.

Read a permission-filtered operation

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics