Backends and Endpoints

A backend describes a model service available to a workspace. An endpoint is a concrete address for that service. The backend ID links the two and is required for updates, probes, and deletion.

Returned objects

ProviderBackend exposes:

Field	Meaning
id, name	Backend identifier and name
type	Provider or protocol type recorded by the service
reasoning_control_protocol	Reasoning-control protocol, when applicable to the backend type
timeout_seconds	Request timeout in seconds
models	Model names configured on the backend
supported_mime_types	MIME types supported by a Parser backend
endpoints	Endpoints returned with the backend
created_at, updated_at	Server-provided time values

ProviderEndpoint contains id, backend_id, address, status, created_at, and updated_at. API keys are intentionally absent from both return types; do not expect a read call to reveal a stored key.

Read a backend and its endpoints

After creating a backend as described in Provider Configuration, use its handle to fetch current state:

current = backend.info()
print(current.id, current.name, list(current.models))

endpoints = backend.endpoints()
for endpoint in endpoints.endpoints:
    print(endpoint.id, endpoint.address, endpoint.status)

current, err := backend.Info(ctx)
if err != nil {
    return err
}
fmt.Println(current.GetId(), current.GetName(), current.GetModels())

endpoints, err := backend.Endpoints(ctx)
if err != nil {
    return err
}
for _, endpoint := range endpoints.GetEndpoints() {
    fmt.Println(endpoint.GetId(), endpoint.GetAddress(), endpoint.GetStatus())
}

An empty endpoint collection means that no endpoint is visible; it is not evidence of an implicit default address.

Update backend configuration

Updates use a separate set of options. Send only fields that need to change instead of writing an older read result back in full.

updated = backend.update(
    sdk.with_provider_backend_update_name(new_name),
    sdk.with_provider_backend_update_timeout_seconds(90),
    sdk.with_provider_backend_update_models(*selected_models),
)

updated, err := backend.Update(
    ctx,
    sdk.WithProviderBackendUpdateName(newName),
    sdk.WithProviderBackendUpdateTimeoutSeconds(90),
    sdk.WithProviderBackendUpdateModels(selectedModels...),
)

The SDK also exposes update options for the API key, reasoning-control protocol, and supported MIME types. Confirm that an option applies to the selected provider family before using it. Model and MIME-type options are lists; the public SDK does not define the server-side meaning of an empty list, so confirm current product behavior before attempting to clear one.

Manage endpoints

Creating an endpoint requires a non-empty address:

created_endpoint = backend.create_endpoint(model_endpoint)
print(created_endpoint.id, created_endpoint.address)

createdEndpoint, err := backend.CreateEndpoint(ctx, modelEndpoint)
if err != nil {
    return err
}
fmt.Println(createdEndpoint.GetId(), createdEndpoint.GetAddress())

Endpoint status is changed through the backend handle:

result = backend.set_endpoint_status(str(endpoint_id), endpoint_status)
if not result.success:
    raise RuntimeError("endpoint status was not updated")

result, err := backend.SetEndpointStatus(ctx, endpointID, endpointStatus)
if err != nil {
    return err
}
if !result.GetSuccess() {
    return errors.New("endpoint status was not updated")
}

The public SDK does not define an allowed status enum. Use a value supplied by the target environment’s API or UI; do not assume strings such as enabled or disabled. Read the endpoint list again after the update to verify server state.

The handle currently has no convenience method for changing an endpoint address or deleting an individual endpoint. Do not fill this gap with guessed HTTP routes; use the current product UI or a published API contract.

Probe a configured backend

models = backend.probe_models(
    sdk.with_provider_backend_api_key(os.environ["MODEL_API_KEY"]),
)

models, err := backend.ProbeModels(
    ctx,
    sdk.WithProviderBackendAPIKey(os.Getenv("MODEL_API_KEY")),
)

An LLM backend probe requires an API key. An Embedding backend can be probed without an additional request body. Parser backends do not support model probing. The returned string list does not automatically replace the backend’s configured models.

Delete a backend

delete() / Delete() deletes the entire backend, not one endpoint. Read fresh state first and confirm that no workflow, knowledge base, or other workspace resource still depends on it.

deleted = backend.delete()
if not deleted.success:
    raise RuntimeError("backend was not deleted")

deleted, err := backend.Delete(ctx)
if err != nil {
    return err
}
if !deleted.GetSuccess() {
    return errors.New("backend was not deleted")
}

After success, list the provider’s backends again and verify that the target ID is no longer visible. The SDK does not define deletion cascade or recovery semantics, so do not treat deletion as automatically reversible.