CumulusDocs
Open Studio
On this page

Configure knowledge embeddings

Choose the embedding model used for knowledge documents.

Operation ID: knowledge.configure.

Request

PUT /api/v1/knowledge

  • TypeScript SDK: client.knowledge.configure (path arguments use path).
  • MCP tool: sdk_client_call with operationId: "knowledge.configure" (path arguments use input.path). Legacy alias: knowledge_configure. Connect to your authenticated /mcp endpoint with an API key for the same environment.
  • Minimum API key role: admin.
  • Idempotency: No header required; the resource or revision identifies the change.

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

Request example

Select a ready embedding model identity returned by models.list for this environment. The environment must have an embedding transport configured for that model. After configuration, inspect knowledge.status; existing documents may need a new embedding generation before retrieval uses it.

Set CUMULUS_BASE_URL to your workspace API URL and CUMULUS_API_KEY to a key for that environment. Example values are synthetic.

cURL

curl
curl --fail-with-body -sS -X PUT "${CUMULUS_BASE_URL%/}/api/v1/knowledge" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model_identity": {
    "model_id": "text-embedding-3-small",
    "provider": "openai",
    "tier": "frontier"
  }
}'

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 response = await client.knowledge.configure({
  "body": {
    "model_identity": {
      "model_id": "text-embedding-3-small",
      "provider": "openai",
      "tier": "frontier"
    }
  }
});

Input schema

Path, query and header parameters

No path or query parameters.

JSON request body

FieldType or valuesRequiredDescription and limits
model_identityobjectRequired—
model_identity.model_idstringRequiredminLength: 1. pattern: \S.
model_identity.providerstringRequiredminLength: 1. pattern: \S.
model_identity.tier"frontier" · "cumulus-served" · "customer-gpu"Required—
Complete OpenAPI schema
OpenAPI JSON
{
  "parameters": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/KnowledgeConfigureRequest"
        }
      }
    }
  }
}

Responses

HTTP 200

Choose the embedding model for knowledge

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
{
  "200": {
    "description": "Choose the embedding model for knowledge",
    "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": {
      "KnowledgeConfigureRequest": {
        "type": "object",
        "properties": {
          "model_identity": {
            "$ref": "#/components/schemas/ModelIdentity"
          }
        },
        "required": [
          "model_identity"
        ],
        "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
      },
      "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
      },
      "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 ebe76561Customer SDKMarkdown source
Configure knowledge embeddings · Cumulus developer docs