LobeHub TypeScript and Python SDKs and File Uploads
Both SDKs are generated from the same OpenAPI specification, so resources and method names match: agents.list is lobehub.agents.list() in TypeScript and client.agents.list() in Python.
import { createLobeHub } from '@lobehub/sdk';
const lobehub = createLobeHub({
apiKey: process.env.LOBEHUB_API_KEY!, // an API key (sk-lh-…) or an OIDC access token
// baseURL: 'https://lobehub.example.com', // a self-hosted deployment
});
Options: apiKey, accessToken (a function returning the current token, which takes precedence over apiKey), baseURL (default https://app.lobehub.com), and any client option such as a custom fetch or headers.
Call Methods
Resources follow the API's top-level paths (agents, topics, messages, files, knowledgeBases, tasks, goals, responses, …). Methods are list, get, create, update, and delete, plus named actions such as files.uploadBatch, tasks.run, and users.me.
Methods do not throw on HTTP errors. They return { data, error, response }, where data is the full response envelope:
For native and desktop apps where each user signs in through a public client (no client secret), such as LobeHub's built-in clients. These helpers never send a client secret, so they do not work with a web OAuth app registered in Settings, which is a confidential client; see OIDC with PKCE.
TypeScript
import {
createAuthorizationUrl,
createLobeHub,
createPkcePair,
exchangeAuthorizationCode,
parseAuthorizationCallback,
refreshAccessToken,
} from '@lobehub/sdk';
const client = { clientId: 'your-public-client-id', redirectUri: 'http://127.0.0.1:8765/callback' };
const state = crypto.randomUUID();
const pkce = await createPkcePair();
const url = createAuthorizationUrl({ ...client, codeChallenge: pkce.challenge, state });
// open `url` in the system browser, then receive `callbackUrl`
const code = parseAuthorizationCallback(callbackUrl, state);
let tokens = await exchangeAuthorizationCode({ ...client, code, codeVerifier: pkce.verifier });
const lobehub = createLobeHub({
accessToken: async () => {
if (tokens.expiresAt - Date.now() < 60_000) {
tokens = await refreshAccessToken({
clientId: client.clientId,
refreshToken: tokens.refreshToken!,
});
// persist tokens.refreshToken: refresh tokens rotate
}
return tokens.accessToken;
},
});
A LobeHubOAuthError with code: 'invalid_grant' means the user has to sign in again.
import { createLobeHub, LobeHubAPIError } from '@lobehub/sdk';
const lobehub = createLobeHub({
apiKey: process.env.LOBEHUB_API_KEY!,
workspaceId: 'ws_xxx', // sent as X-Workspace-Id
maxRetries: 2, // default
timeout: 600_000, // default, ms per attempt
});
// typed errors
const { error } = await lobehub.agents.get({ path: { id } });
if (error instanceof LobeHubAPIError && error.code === 'not_found') {
// error.status, error.code, error.message, error.details, error.requestId
}
// a POST that is safe to retry
await lobehub.agents.create({ body: { title: 'Researcher' }, idempotencyKey: crypto.randomUUID() });
// walk every page
for await (const agent of lobehub.paginate(lobehub.agents.list, { query: { limit: 100 } })) {
console.log(agent.id);
}
// typed stream events
const stream = lobehub.responses.stream({ model: 'agt_xxx', input: 'Summarize my week' });
for await (const event of stream) {
if (event.type === 'response.output_text.delta') process.stdout.write(event.delta);
}
// upload from a path, Blob, File, or bytes
await lobehub.files.upload('./report.pdf', { knowledgeBaseId: 'kb_xxx' });
It also exports LobeHubConnectionError and LobeHubTimeoutError, lets you pass throwOnError: true to throw instead of returning error, and documents each method's API key scopes.
Python SDK
Coming soon (#23337). The lobehub package
is not published to PyPI yet. The examples below show the interface in that pull request and can
change before release.
pip install lobehub
Python 3.9 or later. Both a sync client (LobeHub) and an async client (AsyncLobeHub) are provided. Methods return the data of the response envelope as plain dicts, typed with TypedDict.
Python
from lobehub import LobeHub, NotFoundError
client = LobeHub(api_key="sk-lh-...") # or set LOBEHUB_API_KEY; workspace_id="ws_..." for a Workspace
me = client.users.me()
print(me["id"])
for agent in client.agents.iter_list(limit=50):
print(agent["id"], agent["title"])
agent = client.agents.create({"title": "Reviewer"}, idempotency_key="create-reviewer-1")
try:
client.agents.get("agt_missing")
except NotFoundError as error:
print(error.status_code, error.code, error.request_id)
with client.responses.stream({"model": "agt_...", "input": "Summarize my week"}) as stream:
for event in stream:
if event["type"] == "response.output_text.delta":
print(event["delta"], end="", flush=True)
final = stream.final_response()
Python
import asyncio
from lobehub import AsyncLobeHub
async def main() -> None:
async with AsyncLobeHub() as client:
me = await client.users.me()
print(me["id"])
asyncio.run(main())
Options: api_key, access_token (string or callable), base_url (or LOBEHUB_BASE_URL), workspace_id, timeout (seconds, default 600), and max_retries (default 2). Errors are APIError subclasses by status (BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError), and APIConnectionError / APITimeoutError when no answer arrives. lobehub.oauth provides the same PKCE helpers as the TypeScript SDK.
File Uploads
Uploads are multipart/form-data and need the file:write scope.
files (1–20 files); the same optional fields except skipDeduplication
Limits: up to 100 MB per file, names up to 255 characters, and a type allowlist covering images, video, audio, text, PDF, Office documents, YAML, JSON, Markdown, and CSV. An upload can also be refused when the account is over its storage limit.