CumulusDocs
Open Studio
On this page

Rebuild knowledge embeddings

Build a new searchable generation. Read knowledge status to follow readiness.

Operation ID: knowledge.reembed.

Request

POST /api/v1/knowledge/reembed

  • TypeScript SDK: client.knowledge.reembed (path arguments use path).
  • MCP tool: sdk_client_call with operationId: "knowledge.reembed" (path arguments use input.path). Legacy alias: knowledge_reembed. Connect to your authenticated /mcp endpoint with an API key for the same environment.
  • Minimum API key role: member.
  • Idempotency: Required. Send Idempotency-Key (TypeScript SDK: idempotencyKey) and keep it for retries.

Read resource IDs from earlier responses and use a key for the same environment.

Request example

Starts a new embedding generation using the current configuration. Read knowledge.status until the generation is ready or failed.

Set CUMULUS_BASE_URL to your workspace API URL and CUMULUS_API_KEY to a key for that environment. Set IDEMPOTENCY_KEY to a new UUID for this action and keep it for retries. Example values are synthetic.

cURL

curl
curl --fail-with-body -sS -X POST "${CUMULUS_BASE_URL%/}/api/v1/knowledge/reembed" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'

TypeScript

typescript
import { Cumulus } from "@cumulus/sdk";

const baseUrl = process.env.CUMULUS_BASE_URL;
const apiKey = process.env.CUMULUS_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Set CUMULUS_BASE_URL and CUMULUS_API_KEY");
const client = new Cumulus({ baseUrl, apiKey });

const idempotencyKey = process.env.IDEMPOTENCY_KEY;
if (!idempotencyKey) throw new Error("Set IDEMPOTENCY_KEY for this request");

const response = await client.knowledge.reembed({
  "body": {},
  idempotencyKey,
});

Input schema

Path, query and header parameters

Idempotency-Key

header parameter · Required.

Type: string. minLength: 1. maxLength: 256.

JSON request body

Type: object.

Complete OpenAPI schema
OpenAPI JSON
{
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/KnowledgeReembedRequest"
        }
      }
    }
  }
}

Responses

HTTP 202

Build a new knowledge generation

application/json

FieldType or valuesRequiredDescription and limits
configuredbooleanRequired—
model_identityobject or nullRequired—
model_identity · combined section 1object—Fields for this schema branch.
model_identity.model_idstringRequired in a non-null parentminLength: 1. pattern: \S.
model_identity.providerstringRequired in a non-null parentminLength: 1. pattern: \S.
model_identity.tier"frontier" · "cumulus-served" · "customer-gpu"Required in a non-null parent—
dimensioninteger or nullRequiredGreater than 0. At most 9007199254740991.
generationobject or nullRequired—
generation.generation_idstring (uuid)Required in a non-null parentpattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
generation.state"building" · "ready" · "failed"Required in a non-null parent—
generation.document_countintegerRequired in a non-null parentAt least 0. At most 9007199254740991.
generation.created_atstring (date-time)Required in a non-null parentpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
pending_documentsintegerRequiredAt least 0. At most 9007199254740991.

Error responses

HTTPDescription
4XXTyped error (ApiError)
5XXTyped error (ApiError)

Errors use the shared error envelope. Inspect error.code, retryable, outcome and details before retrying.

Complete OpenAPI schema
OpenAPI JSON
{
  "202": {
    "description": "Build a new knowledge generation",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/KnowledgeStatus"
        }
      }
    }
  },
  "4XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "5XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

Referenced schemas

Expand the complete OpenAPI definitions for integrations that generate their own clients.

Complete OpenAPI schema
OpenAPI JSON
{
  "components": {
    "schemas": {
      "KnowledgeReembedRequest": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      },
      "KnowledgeStatus": {
        "type": "object",
        "properties": {
          "configured": {
            "type": "boolean"
          },
          "model_identity": {
            "nullable": true,
            "allOf": [
              {
                "$ref": "#/components/schemas/ModelIdentity"
              }
            ]
          },
          "dimension": {
            "nullable": true,
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": true,
            "maximum": 9007199254740991
          },
          "generation": {
            "nullable": true,
            "type": "object",
            "properties": {
              "generation_id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
              },
              "state": {
                "type": "string",
                "enum": [
                  "building",
                  "ready",
                  "failed"
                ]
              },
              "document_count": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
              }
            },
            "required": [
              "generation_id",
              "state",
              "document_count",
              "created_at"
            ],
            "additionalProperties": false
          },
          "pending_documents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "configured",
          "model_identity",
          "dimension",
          "generation",
          "pending_documents"
        ],
        "additionalProperties": false
      },
      "ModelIdentity": {
        "type": "object",
        "properties": {
          "model_id": {
            "type": "string",
            "minLength": 1,
            "pattern": "\\S"
          },
          "provider": {
            "type": "string",
            "minLength": 1,
            "pattern": "\\S"
          },
          "tier": {
            "type": "string",
            "enum": [
              "frontier",
              "cumulus-served",
              "customer-gpu"
            ]
          }
        },
        "required": [
          "model_id",
          "provider",
          "tier"
        ],
        "additionalProperties": false
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthenticated",
                  "forbidden",
                  "not_found",
                  "conflict",
                  "invalid_request",
                  "idempotency_conflict",
                  "policy_denied",
                  "capability_unavailable",
                  "provider_unavailable",
                  "knowledge_unavailable",
                  "publication_invalid",
                  "run_not_active",
                  "rate_limited",
                  "outcome_unknown",
                  "internal"
                ]
              },
              "message": {
                "type": "string"
              },
              "retryable": {
                "type": "boolean"
              },
              "outcome": {
                "type": "string",
                "enum": [
                  "none",
                  "unknown"
                ]
              },
              "details": {
                "type": "object",
                "additionalProperties": {}
              }
            },
            "required": [
              "code",
              "message",
              "retryable",
              "outcome"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      }
    }
  }
}

Errors and recovery

See API error handling and Troubleshooting.

Content version 3d0bf525Customer SDKMarkdown source
Rebuild knowledge embeddings · Cumulus developer docs