Skip to main content

Run Omega index jobs

Omega index jobs update an authorized semantic index without loading one unbounded snapshot into a client request. Jobs report durable progress, estimated and actual credit use, warnings, and a terminal state.

The public API exposes estimation, start, inspection, cancellation, dimension-migration activation, and dimension-migration rollback. It does not expose a general resume operation in the current live contract.

Choose a mode​

ModeUse
estimateCalculate expected scope and credits without starting an indexing run.
fullRebuild the authorized index scope.
incrementalAdd or refresh changed entries.
cleanupRemove stale index state.
tombstoneProcess deleted-source markers.
dimension_migrationStage a change to a supported embedding dimension for separate activation.

Estimate or start a job​

POST /v1/graymatter/omega/index-jobs

Estimate first:

{
  "mode": "estimate",
  "targetTypes": ["MemoryEntry"]
}

Start an incremental job with an idempotency key:

{
  "mode": "incremental",
  "idempotencyKey": "memory-entry-incremental-2026-07-18-v1",
  "targetTypes": ["MemoryEntry"]
}

Identity and tenant scope are server-derived. Do not send owner, tenant, audit, provider, model, or credit values.

Inspect or cancel a job​

GET /v1/graymatter/omega/index-jobs/{jobId}
POST /v1/graymatter/omega/index-jobs/{jobId}/cancel

Job states are estimated, queued, running, awaiting_activation, completed, failed, canceled, and rolled_back.

Use entriesProcessed, entriesIndexed, entriesFailed, estimatedCredits, actualCredits, and warnings to report progress. A queued or running response is not proof that indexing completed.

Change embedding dimensions​

Dimension migration is a staged operation. Include a supported target dimension in the start request:

{
  "mode": "dimension_migration",
  "idempotencyKey": "memory-dimensions-1536-v1",
  "targetEmbeddingDimensions": "1536",
  "expectedSourceEmbeddingDimensions": ["384"]
}

When the job reaches awaiting_activation, activate it with the exact server-issued profile hash:

POST /v1/graymatter/omega/index-jobs/{jobId}/activate
{
  "expectedProfileHash": "<server-issued SHA-256 profile hash>"
}

Use the same optimistic binding to roll back a staged migration:

POST /v1/graymatter/omega/index-jobs/{jobId}/rollback

Do not activate or roll back when the profile hash has changed. Reinspect the job and resolve the configuration drift first.

Operational guidance​

  • Estimate credit use before a large rebuild.
  • Use one idempotency key per logical start request.
  • Poll with bounded backoff; do not treat an accepted job as completed work.
  • Surface failed, canceled, warnings, and nonzero failure counts to an operator.
  • Keep production activation and rollback behind the normal human approval process.