LobeHub Public API Overview and Quick Start
The public API lets your own application, script, or agent read and act on a LobeHub account or Workspace: Agents, Topics, messages, files, Libraries, tasks, goals, and model calls. It is a REST API under /api/v1, described by an OpenAPI 3.1 specification, with an official TypeScript SDK generated from that specification.
This guide only describes behavior that exists in LobeHub source code. Each capability carries one of two labels:
- Available: merged into the
canarybranch, which runs LobeHub Cloud. - Coming soon: implemented in an open pull request that has not been merged. Names, fields, and limits can still change before release. Do not build production integrations on them yet.
Guide Contents
| Page | What it covers |
|---|---|
| Authentication and Scopes | API keys, OIDC with PKCE, OAuth apps, X-Workspace-Id, and the scope table |
| Errors, Pagination, Rate Limits, and Retries | Error format and code catalog, pagination, rate limits, Idempotency-Key, and retry advice |
| Streaming, Runs, and Human Approval | POST /responses stream events, Agent run events, approvals, and client tool results |
| Webhooks | Event catalog, delivery format, and signature verification |
| MCP Server | Connecting Claude Code, Cursor, or Codex to LobeHub over MCP |
| SDKs and File Uploads | TypeScript and Python SDK examples, and uploading files |
| Versioning, Deprecation, and Changelog | Compatibility rules and the API changelog |
Availability at a Glance
| Capability | Status | Source |
|---|---|---|
REST API under /api/v1 with typed success responses | Available | #23217 |
API key and OIDC bearer authentication, X-Workspace-Id | Available | packages/openapi/src/middleware |
TypeScript SDK @lobehub/sdk (createLobeHub, OAuth PKCE helpers) | Available | packages/sdk |
POST /responses streaming, task runs, multipart file upload | Available | packages/openapi/src/routes |
| Unified error codes, cursor pagination, rate limits, idempotency | Coming soon | #23231 |
SDK retries, typed errors, paginate, responses.stream, workspaceId | Coming soon | #23246 |
| Agent runs API with event stream and human approval | Coming soon | #23253 |
| Developer webhooks with HMAC signatures | Coming soon | #23272 |
MCP server at /api/v1/mcp | Coming soon | #23318 |
OAuth open platform (dynamic registration, client_credentials, API scopes) | Coming soon | #23322 |
Python SDK lobehub | Coming soon | #23337 |
The full list of merged and pending changes is in the API Changelog.
Quick Start
1. Create an API Key
- Open the Workspace where your data lives and go to Settings → API Keys (
/<workspace>/settings/apikey). - Create a key. Choose Full access or pick only the scopes your integration needs.
- Copy the key. It starts with
sk-lh-and is followed by 16 lowercase letters and digits.
You can change a key's scopes later on its detail page. Only the key's creator can do this.
2. Send a First Request
A successful response is wrapped in an envelope:
For a self-hosted instance, replace https://app.lobehub.com with your deployment's origin. The base path is always /api/v1.
3. Choose the Workspace
A key created inside a Workspace is bound to it: requests run in that Workspace without extra headers. An OIDC access token can address a Workspace by sending its id:
See Workspace selection for the full rules.
4. Explore the Specification
- Interactive reference:
https://app.lobehub.com/api/v1/docs - Machine-readable spec:
https://app.lobehub.com/api/v1/openapi.json - Source spec in the repository:
packages/openapi/openapi.yml
Internal application routes (/trpc/*, /webapi/*) are not part of the public API and can change without notice.
5. Use the TypeScript SDK
npm install @lobehub/sdkMore examples are in SDKs and File Uploads.