Model backend administration objects and rules

Manage LLM/Embedding backends, access endpoints, and routing in the current Workspace. Root-level and Workspace-level protocols access the same kinds of owner, but differ in fields, defaults, envelopes, and successful HTTP statuses.

Before you call this API

BASE_URL, MOI_KEY, and WORKSPACE_ID come from the same environment. Obtain BACKEND_ID/ENDPOINT_ID from reads in that environment and the same kind. Provider credential provider-key-example and URLs are placeholders; replace them before actual calls. Production deployment support requires separate confirmation.

Root-level /llm and /embedding select the tenant through X-Workspace-ID; they are not global administrator configuration. Workspace-level /workspaces/{id}/llm and /embeddings select the Workspace in the path. Ordinary product authentication and validated task identities are handled separately. These examples use ordinary identities and do not establish acceptance of the full task-calling flow.

Canonical backend identity includes kind and numeric ID. The same integer may belong to different kinds and cannot be reused across them. Administration paths accept only canonical positive decimal IDs; 0, negatives, leading zeroes, and plus signs are rejected. Synthetic negative system identities in model lists cannot be used directly for these operations.

Task

Permission

Backend collection/details and endpoint collection

model_backend.read; collections are filtered by the currently effective role.

Create backend

Workspace model_backend.create; creation results are associated with the Ownership lifecycle.

Update backend, create endpoint, or write status

model_backend.update on the specified backend.

Delete backend

model_backend.delete on the specified backend, entering the deletion lifecycle.

Read/write Router

Workspace model_router.read / model_router.update.

Model execution has no separate model_backend.use permission. Actual Agent/task/data access follows its own formal admission boundaries. Reading configuration or modifying a Router does not grant actual inference, data, or paid-resource access.

Response structures

Item

Root-level

Workspace-level

Success envelope

code=”OK”, msg=”OK”, data

code=0, data; 204 has no response body.

Backend list

data.backends, possibly null; no total

data.backends and total; empty fields may be omitted.

Backend object

data directly contains the backend and may include endpoints

data directly contains the backend, omits zero-valued fields, and does not include endpoints.

Endpoint list

data.endpoints, possibly null

data is directly an array, [] when empty.

Router

data directly contains the configuration

data.config contains the configuration.

Create backend/endpoint

HTTP 200

HTTP 201。

Delete backend

HTTP 200,data.success=true

LLM 204;Embedding 200,data.deleted=true。

Set endpoint status

HTTP 200,data.success=true

LLM 204;Embedding 200,data.updated=true。

Backend fields

Field

Type

Description

id

integer

Backend ID within the current kind.

name

string

Backend name.

type

string or integer

String for root-level; numeric for Workspace-level.

timeout_seconds

integer

Configured timeout in seconds.

models

array (strings)

Declared model names. May be null for root-level or omitted when empty for Workspace-level.

reasoning_control_protocol

string or integer

LLM reasoning-control protocol; fixed NONE/0 for Embedding.

created_at

integer

Unix seconds. Zero times may be omitted for Workspace-level.

updated_at

integer

Unix seconds. Zero times may be omitted for Workspace-level.

endpoints

array (objects)

May appear in root-level reads. LLM includes online entries only; Embedding retains both states. Update results omit it.

api_key_encrypted

string

Workspace-level write results may return saved values; lists/details actively remove them.

provider_origin

string

Workspace-level source. LLM accepts external_provider; Embedding returns unknown.

origin_ref

string

Workspace-level LLM source reference; omitted when empty.

origin_version

string

Workspace-level LLM source version; omitted when empty.

Root-level responses do not return credentials. Workspace-level creation/updates use an unredacted converter, so nonempty saved values may appear in api_key_encrypted. Lists/details use a redacted converter and omit it. The field name does not establish encryption or automatic client-side encryption. Use placeholders only in examples and records.

Workspace-level backend type maps 0 OPENAI, 1 OLLAMA, 2 VLLM, 3 QIANWEN, 4 DOUBAO, 5 DEV_LLM, and 6 HTTP. Embedding creation rejects DEV_LLM. Configuration acceptance does not establish production routing support. Generic LoadLLMWorkspaceConfig rejects DEV_LLM/HTTP; chat uses LoadChatCompletionWorkspaceConfig, which allows DEV_LLM but rejects HTTP. Do not conflate these loaders or treat development adapters as production support.

Workspace-level LLM reasoning control values 0–5 map to NONE, OPENAI_REASONING_EFFORT, CHAT_TEMPLATE_KWARGS_ENABLE_THINKING, CHAT_TEMPLATE_KWARGS_THINKING, OLLAMA_THINK, and QIANWEN_ENABLE_THINKING. Root-level accepts corresponding names and official REASONING_CONTROL_* strings. Actual model support requires separate testing.

Endpoint fields

Field

Type

Description

id

integer

Endpoint ID.

backend_id

integer

Owning backend ID.

address

string

Access URL.

status

string or integer

Root-level ONLINE/OFFLINE; Workspace-level 0/1.

created_at

integer

Unix seconds.

updated_at

integer

Unix seconds.

LLM endpoint lists, backend lists, and backend details filter out offline entries; Embedding retains both states. Save an endpoint’s creation ID before setting it offline: these reads cannot retrieve offline LLM endpoint IDs afterward. Workspace-level status=0 may be omitted in HTTP, while the SDK default remains online; omission does not mean unknown. Online/offline changes configuration, without testing health or deleting endpoints.

Router fields

Root-level field

Workspace-level field

Type/meaning

strategy

strategy

ROUND_ROBIN/LEAST_CONNECTIONS/MODEL_BASED strings, or corresponding integers 0/1/2.

health_check_interval

health_check_interval_seconds

Positive seconds.

max_retries

max_retries

Retry configuration; see the comparison page for protocol-specific defaults.

session_affinity

enable_session_affinity

boolean. Omission/null writes false.

None

id

Configuration record ID; omitted when zero.

None

created_at

Unix seconds; omitted when zero.

None

updated_at

Unix seconds; omitted when zero.

Router PUT writes complete configuration. Unspecified fields do not preserve old values. Owner reads return defaults when the configuration row is absent, while DAO writes update existing records instead of creating them. Real missing-row behavior requires separate verification; reading defaults does not establish initialization. Back up before writing, read back afterward, and verify routing using real model requests. Recover and clean up only within the same environment.

Errors and result confirmation

Root-level uses string code/msg; Workspace-level uses integer code/message. Invalid parameters/enums and missing objects may return 400/404 respectively; authorization rejection uses 403 and dependency failure 503. Other mappings depend on the entry point. Invalid root-level reasoning protocols may return 500/ErrServer, while invalid Workspace-level numbers are rejected during binding/mapping. Do not reuse one error table for both.

Embedding DAO handling of zero matches for deletion or endpoint status differs from LLM. Formal IAM/object lifecycle checks may reject requests before the DAO. Storage branches do not establish public API idempotency or success for arbitrary missing IDs. The specification requires stable reference-conflict errors, but complete reference admission still needs review; do not assume deletion has no effects.

Request binding does not uniformly reject unknown keys or trailing JSON. Confirm field acceptance, HTTP success, SDK decoding, and actual target value changes separately.

Last updated on