OrdinateDB

Documentation

product Pre-releaseunwritten sections are marked
POST/v1/jobs/retention-backfill

Enqueue a confirmed retention backfill

operation ID: post_v1_jobs_retention_backfill

Overview

Enqueue a confirmed retention backfill. Collector and job operations expose ingestion diagnostics and managed storage work.

When to use it

  • Use it when an application needs to enqueue a confirmed retention backfill.
  • Use it when an operator is monitoring data ingestion or coordinating a storage-maintenance 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/jobs/retention-backfill" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "series_uuid": "00000000-0000-4000-8000-000000000001",
    "policy_version": 0
  }'

Expected output · 202

Backfill accepted

Example 202 output

{
  "job_id": 0
}

The cURL request sends the smallest contract-derived body and asks OrdinateDB to enqueue a confirmed retention backfill. The documented 202 response is backfill accepted.

How it works

These routes report server-managed collector or job state; collector writes themselves use the separate gRPC ingest contract.

Reference

Required capability
admin
Authorization scope
handler-resolved target

Parameters

NameInRequiredType and constraints
Idempotency-Keyheaderno
string

Replays the first successful response for the same authenticated principal, route, key, and request body

max length: 255

Request body

application/json

confirmbooleanoptional
policy_versionintegerrequired
format: int64
series_uuidstringrequired
format: uuid
unknown fields rejected

Example request body

{
  "series_uuid": "00000000-0000-4000-8000-000000000001",
  "policy_version": 0
}

Responses

202Backfill accepted

Response headers

  • X-Ordinate-Idempotent-ReplayPresent with the literal value `true` when this response was replayed

application/json

job_idintegerrequired
format: int64
unknown fields rejected

Example 202 output

{
  "job_id": 0
}
400Explicit confirm:true or a valid series UUID is required; Invalid or oversized 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"
}

text/plain

string
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"
}
403Admin capability is not granted at the staging root

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"
}
409A matching backfill is already in flight; Idempotency-Key was already used with a different request body

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

text/plain

string

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/jobs/retention-backfill`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "series_uuid": "00000000-0000-4000-8000-000000000001",
  "policy_version": 0
})
});

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

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

Related topics