Console SDK(Node.js / JavaScript)
Before running the examples, replace <APPBASE_ENDPOINT_WITH_V1>, <APPBASE_CONSOLE_ORIGIN>, and <APPBASE_CONSOLE_HOST> where used with values for the intended environment, and verify that the project and credentials belong to that environment.
The Console SDK targets management-plane callers: Console panel capabilities, organization and project governance, and cross-project operations automation, authenticated with a management identity—an email-password Session or a short-lived JWT. npm coordinate agentbase-console-sdk@2.12.0. See the same directory for the Java / Python / Go surfaces: java.md / python.md / go.md; for the browser frontend use the Client SDK; for the server-side data plane use the Server SDK.
Installation and initialization
npm install agentbase-console-sdk@2.12.0 --save-exactMethod One: sdk wrapper object (recommended; manages endpoints and modes automatically)
import { sdk, realtime } from 'agentbase-console-sdk';
sdk.forConsole.projects.list(/* Organization/Console-level calls */);
sdk.forConsoleIn('default').health.get(); // Specify region
sdk.forProject('default', '<projectId>').tablesDB.listRows(...); // Project resource plane; automatically calls setProject + setMode('admin')Method Two: bare Client (when fine-grained authentication control is needed)
import { Client } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
.setProject('<consoleOrProjectId>'); // X-Appwrite-Project headerAuthentication loading (choose one of three; mutually exclusive):
Email-password Session: after
account.createEmailPasswordSession({ email, password }), load the session cookie (the automatic login flow intercepts the responseset-cookieandclient.setCookie(...)).Short-lived JWT:
client.setJWT(token)—short-lived credential; do not write to logs.SQL-scenario project API Key:
client.setProject('<应用项目ID>').setKey('<项目APIKey>')—used by the Sql service to point to the application project.
Other setters: setMode('admin'), setLocale, setSelfSigned.
5-minute quick start (management automation)
const projects = sdk.forConsole.projects;
const project = await projects.create({
projectId: 'unique()', name: 'My Project', teamId: '<teamId>', region: 'default',
});
const key = await projects.createKey(project.$id, 'server key', [
'users.read', 'users.write', 'teams.read', 'teams.write',
]);
// key.secret appears only once in the creation response; hand it to the server for secure storage immediatelyOn the server side, get a Key and integrate with the Server SDK; governance-plane tasks such as domain rules, migrations, and backups continue to use the services on this page.
Console-exclusive services
| Service | Covers |
|---|---|
Organizations | Administrative capabilities such as organization members and billing; instantiated separately by the Console Client as an export class, not on the sdk.forConsole wrapper object |
Proxy | Site/API/function/redirect domain rules (createSiteRule / listRules / getRule / updateRuleVerification / deleteRule) |
Vcs | Git integration: installations, repository discovery, branch lists, repository content, external deployment status write-back |
Migrations | Migration jobs (Appwrite/Firebase/Supabase/NHost/AppBase/CSV import-export): create, report, retry, delete; also includes SchemaMigration (a TablesDB-based schema planning/execution assistant) |
Assistant | assistant.chat() Management-side AI assistant |
Console | Platform metadata: listRegions / listTags, plan and resource queries, column/index suggestions (suggestColumns / suggestIndexes), variables |
Admin | Platform management: pool/label lists, storage migration, project table schema conversion, project deletion audit and recovery |
Activities / Backups / Domains | Event streams, backup policies and archives, domain assets |
Create a project, issue a backend key, and register a Web platform
The example uses agentbase-console-sdk@2.12.0. Provide a short-lived management JWT for the target Console, a Web hostname you can register in APPBASE_WEB_HOSTNAME, and permissions to create an organization and project. Omit region so the service uses its configured default.
import { Client, Projects, Teams, ID, Scopes, PlatformType } from 'agentbase-console-sdk';
function refuseAutomaticRedirects(client: Client) {
const originalPrepareRequest = client.prepareRequest;
if (typeof originalPrepareRequest !== 'function') throw new Error('Redirect control unavailable');
client.prepareRequest = function (...args) {
const request = originalPrepareRequest.apply(this, args);
request.options.redirect = 'error';
return request;
};
}
const token = process.env.APPBASE_ADMIN_JWT;
if (!token) throw new Error('Set APPBASE_ADMIN_JWT for the target Console');
const webHostname = process.env.APPBASE_WEB_HOSTNAME;
if (!webHostname) throw new Error('Set APPBASE_WEB_HOSTNAME');
// 1. Initialize the management-plane Client (first point it at the console project to complete organization and project provisioning)
const consoleClient = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT ?? '<APPBASE_ENDPOINT_WITH_V1>')
.setProject(process.env.APPBASE_CONSOLE_PROJECT_ID ?? 'console')
.setJWT(token);
refuseAutomaticRedirects(consoleClient);
const teams = new Teams(consoleClient);
const projects = new Projects(consoleClient);
// 2. Create an organization (Team) and a Shared V2 enterprise project
const org = await teams.create({
teamId: '69c6d1aa00062e6bb60',
name: 'Agentbase 企业智能中台',
});
const project = await projects.create({
projectId: '<APPBASE_PROJECT_ID>',
name: '企业智能客服与知识中台',
teamId: org.$id,
});
// 3. Issue an API Key with a minimal permission set for backend services (the secret is returned only once, in the creation response)
const serverKey = await projects.createKey({
projectId: project.$id,
name: 'prod-backend-service-key',
scopes: [
Scopes.UsersRead,
Scopes.UsersWrite,
Scopes.TablesRead,
Scopes.TablesWrite,
Scopes.RowsRead,
Scopes.RowsWrite,
],
});
// Store the key from this creation response directly in your secret manager.
// 4. Register frontend Web platform domains (enables browser CORS trust; only Console Session/JWT can call)
await projects.createPlatform({
projectId: project.$id,
type: PlatformType.Web,
name: 'Enterprise Support Portal',
hostname: webHostname,
});After creating the project, configure its database and follow the SQL Proxy guide to run parameterized queries. After creating a knowledge base, use the lexicon guide to create and bind a lexicon.
Selection comparison: Console SDK vs. Server SDK vs. Client Web SDK
| Dimension | Console SDK (agentbase-console-sdk@2.12.0) | Server SDK (agentbase-node-sdk@2.12.0) | Client Web SDK (agentbase-web-sdk@2.12.0) |
|---|---|---|---|
| Core positioning | Organization and project lifecycle governance, platform registration, domain rules, migrations, backups, SQL endpoint | Business backend data-plane reads/writes, user management, RAG knowledge base, memory, model gateway, and observability reporting | Browser-side user login sessions, RLS-protected data reads/writes, and Realtime subscriptions |
| Auth credentials | Admin Session Cookie / short-lived JWT (project API Key supported for SQL scenarios) | Project API Key (X-Appwrite-Key, bypasses RLS) | End-user Session Cookie / JWT (strictly enforces RLS row-level permissions) |
| Exclusive capabilities | Organizations, Projects.create/createKey/createPlatform, Proxy, Vcs, Migrations, Admin, Backups, Sql | Users.createToken (Custom Token issuance) and full project-level server-side batch processing | Account Browser OAuth redirect login, Realtime WebSocket subscriptions (shares realtime capabilities with Console) |
Versions and SDK support
The published npm coordinate is fixed as
agentbase-console-sdk@2.12.0(and the internal mirror@alipay/agentbase-console-sdk@2.12.0); see ../integration.md for installation verification details.Lexicon management can be performed via REST interfaces (including
/v1/lexicons,/v1/lexicons/{lexiconId}/entries,/v1/lexicons/{lexiconId}/preview,/v1/lexicons/{lexiconId}/import,/v1/lexicons/{lexiconId}/export,/v1/lexicons/{lexiconId}/references,/v1/knowledgebases/{knowledgeBaseId}/lexicons, and/v1/agent-runtime/agents/{agentId}/lexicons). Use a backend HTTP client with the relevant project permissions and automatic redirects disabled.
Functional surface navigation (governance domain → services)
| Domain | Services and method highlights | Feature documentation |
|---|---|---|
| Organization | Organizations: members, billing address, invoices, top-ups, organization Keys, listUsageAggregates({ organizationId }); instantiated by new Organizations(client) | ../organization.md, ../usage.md |
| Project lifecycle | Projects.create({ projectId, name, teamId, region: 'default', poolTag }) / get / update / delete / list | ../overview.md |
| Project Keys and platforms | projects.createKey (scope as a lowercase dot-separated string; secret visible only at creation time), createDevKey, createPlatform / listPlatforms (Console Session only), updateOAuth2 | ../overview.md |
| Quotas and rate limits | Project projects.getQuotaLimits / updateQuotaLimits; account account.getQuotaLimits / updateQuotaLimits / deleteQuotaLimits (no listLimitsProjects); /limits via client.call | ../limits.md |
| Three-level usage | sdk.forConsole.account / sdk.forConsole.projects and the standalone Organizations service's listUsageAggregates() (the most recent 30 UTC days) | ../usage.md |
| Project resource plane | TablesDB / Sql / Sites / Functions / Storage / Messaging / Memory (including project configuration and rollback) / Users / Teams / Tokens / LLMGateway (including usage) / Webhooks / Graphql / Avatars / Locale / Health | Feature pages (../misc/webhooks.md, etc.) |
| SQL | Sql.query / Sql.execute (exclusive to the JS Console SDK; for the Java / Python / Go Console surfaces see each page's notes) | ../databases/sql-proxy.md |
| Sites and domains | Sites full set + Proxy domain rules + Domains | ../sites.md |
| Realtime | realtime.forProject(region, channels, cb) / realtime.forConsole(...) | ../realtime.md |
| Platform operations | Admin / Backups / Activities / Health (including management-plane queue checks) | ../misc/webhooks.md |
Errors and boundaries
Error model:
AppBaseException(code/type).Platform registration (
createPlatform) and organization queries are Console-only operations and cannot use project API Keys; for project resource operations, it is recommended to proceed aftersetProject(应用项目).The Console Session cookie and OAuth test Sessions are mutually isolated; JWTs are valid short-term and must be re-issued after expiration.
Example Guide
JavaScript Console initialization and typical calls: ../examples/javascript.md