Models, connections, and Workspaces API

Provider connections store workspace-level credentials and connection settings. Models select an LLM on a provider connection. Workspace routes expose the authenticated workspace, related resources, and usage limits.

All requests require Authorization: Bearer YOUR_API_KEY and use https://api.klu.ai/v1. Provider connection responses do not return key. The Model create response is an exception described below and must be treated as sensitive.

Model endpoints

curl --request POST 'https://api.klu.ai/v1/models' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "llm":"gpt-4.1-mini",
    "provider":"openai",
    "key":"PROVIDER_API_KEY",
    "default":true
  }'

llm, provider, and key are required. url is optional for compatible/custom endpoints, and default defaults to false. Model list, detail, update, and delete responses use public fields such as guid, llm, nullable provider name and provider GUID, default, timestamps, creator, and deleted.

POST /models currently returns the persistence-shaped Model record rather than that public representation. It includes numeric id, workspaceId, workspaceModelProviderId, nullable providerId, camel-case timestamps/creator fields, and the submitted key. Do not log or expose this create response. Fetch /models/{guid} afterward when you need the normalized public representation.

Model listing returns a bare array. It accepts skip and limit, defaulting to 0 and 100, but does not return a total count or has_next_page. Continue until a page contains fewer than limit entries. Model updates are CRUD-only and accept only llm; change credentials or endpoint settings through the Provider routes.

Provider connection endpoints

The flexible create contract accepts:

curl --request POST 'https://api.klu.ai/v1/providers' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "provider":"openai",
    "name":"Production OpenAI",
    "key":"PROVIDER_API_KEY",
    "default":true,
    "model":"gpt-4.1-mini"
  }'

Provider responses contain guid, nullable name, nickname, nullable url, default, timestamps, and creator. They never echo the credential. Provider type, catalog ID, metadata requirements, and URL support vary by provider; use settings accepted by the connection you configured in Klu.

The public create route does not accept providerId; identify the catalog provider with provider. Provider update requires nickname and optionally accepts default. It does not rotate key, change url, or replace metadata. Create a replacement connection when those values need to change.

Provider listing is a bare array with no public pagination or filters. Delete returns { "message": "Model provider PROVIDER_GUID deleted" }. Deleting a Provider can make Models and Actions that depend on it unusable; move workloads to another connection first.

Workspace endpoints

Create requires a name and slug; update requires name. Workspace responses contain guid, slug, name, deleted, and timestamps. Workspace list accepts skip and limit with 0/100 defaults and returns the standard pagination envelope.

Usage returns a bare array:

[
  { "feature": "apps", "used": 3, "limit": 10 },
  { "feature": "members", "used": 5, "limit": 20 }
]

Related-resource routes return compact bare arrays. For full contracts, follow with the resource's detail endpoint. The current-workspace route is the simplest way to discover the Workspace GUID selected by your API key.

Deleting a Workspace is high impact because its API-scoped resources become unavailable. The API does not provide a restore endpoint in this public router.

SDK examples and limits

from klu import Klu

klu = Klu("YOUR_API_KEY")
models = await klu.models.list(skip=0, limit=100)

The SDKs retain older Provider paths (/models/provider/ in Python and /provider/ in TypeScript) and singular /workspace/ paths that do not match the current public routers. Use REST for Provider and Workspace operations. TypeScript also intentionally removes general Model update from the public klu.models type, although REST supports changing llm. See SDK exports for the full surface.

Errors

Invalid provider/model fields return 400. Missing Models, Providers, or Workspaces return 404. Credential validation and upstream-provider failures can surface during creation or the first model request. Workspace feature limits can reject resource creation; inspect /workspaces/{guid}/usage when available and treat response status/detail as authoritative.