The base44 SDK is the library to communicate with base44 services. In projects, you use it to communicate with remote resources (entities, backend functions, realtime actors, ai agents, and the AI gat
1---2name: base44-sdk3description: The base44 SDK is the library to communicate with base44 services. In projects, you use it to communicate with…4---56# skills/base44-sdk/SKILL.md
B
SKILL.mdAgent skill
Transport
File
Status
Listed
SKILL.md
Install
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
shterminal
1npx skills add base44/skills --skill base44-sdk -a cursor -y
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
The base44 SDK is the library to communicate with base44 services. In projects, you use it to communicate with remote resources (entities, backend functions, realtime actors, ai agents, and the AI gateway for code agents, image, video, and speech generation, and AI decisions) and to write backend functions and actors. This skill is the place for learning about available modules and types, including actors — the realtime/WebSocket primitive for multiplayer, collaborative boards, presence and live cursors, in-room chat, and live auctions. When you plan or implement a feature, you must learn this skill
Download skills/base44-sdk/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does base44-sdk live?
The publisher keeps it at https://github.com/base44/skills.
Which agents can use base44-sdk?
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.
From the publisher
SKILL.md
name
base44-sdk
description
The base44 SDK is the library to communicate with base44 services. In projects, you use it to communicate with remote resources (entities, backend functions, realtime actors, ai agents, and the AI gateway for code agents, image, video, and speech generation, and AI decisions) and to write backend functions and actors. This skill is the place for learning about available modules and types, including actors — the realtime/WebSocket primitive for multiplayer, collaborative boards, presence and live cursors, in-room chat, and live auctions. When you plan or implement a feature, you must learn this skill
Base44 Coder
Build apps on the Base44 platform using the Base44 JavaScript SDK.
⚡ IMMEDIATE ACTION REQUIRED - Read This First
This skill activates on ANY mention of "base44" or when a base44/ folder exists. DO NOT read documentation files or search the web before acting.
Your first action MUST be:
Check if base44/config.jsonc exists in the current directory
If YES (existing project scenario):
This skill (base44-sdk) handles the request
Implement features using Base44 SDK
Do NOT use base44-cli unless user explicitly requests CLI commands
If NO (new project scenario):
Transfer to base44-cli skill for project initialization
This skill cannot help until project is initialized
When to Use This Skill vs base44-cli
Use base44-sdk when:
Building features in an EXISTING Base44 project
base44/config.jsonc already exists in the project
Base44 SDK imports are present (@base44/sdk)
Writing JavaScript/TypeScript code using Base44 SDK modules
Implementing functionality, components, or features
User mentions: "implement", "build a feature", "add functionality", "write code for"
User says "create a [type] app" and a Base44 project already exists
DO NOT USE base44-sdk for:
❌ Initializing new Base44 projects (use base44-cli instead)
❌ Empty directories without Base44 configuration
❌ When user says "create a new Base44 project/app/site" and no project exists
base44-sdk assumes a Base44 project is already initialized
base44-cli is a prerequisite for base44-sdk in new projects
If user wants to "create an app" and no Base44 project exists, use base44-cli first
State Check Logic:
Before selecting this skill, verify:
IF (user mentions "create/build app" OR "make a project"):
IF (directory is empty OR no base44/config.jsonc exists):
→ Use base44-cli (project initialization needed)
ELSE:
→ Use base44-sdk (project exists, build features)
Quick Start
// In Base44-generated apps, base44 client is pre-configured and available
// CRUD operations
const task = await base44.entities.Task.create({ title: "New task", status: "pending" });
const tasks = await base44.entities.Task.list();
await base44.entities.Task.update(task.id, { status: "done" });
// Get current user
const user = await base44.auth.me();
// External apps
import { createClient } from "@base44/sdk";
// IMPORTANT: Use 'appId' (NOT 'clientId' or 'id')
const base44 = createClient({ appId: "your-app-id" });
await base44.auth.loginViaEmailPassword("[email protected]", "password");
⚠️ CRITICAL: Do Not Hallucinate APIs
Before writing ANY Base44 code, verify method names against this table or QUICK_REFERENCE.md.
Base44 SDK has unique method names. Do NOT assume patterns from Firebase, Supabase, or other SDKs.
Authentication - WRONG vs CORRECT
❌ WRONG (hallucinated)
✅ CORRECT
signInWithGoogle()
loginWithProvider('google')
signInWithProvider('google')
loginWithProvider('google')
auth.google()
loginWithProvider('google')
signInWithEmailAndPassword(email, pw)
loginViaEmailPassword(email, pw)
signIn(email, pw)
loginViaEmailPassword(email, pw)
createUser() / signUp()
register({email, password})
onAuthStateChanged()
me() (no listener, call when needed)
currentUser
await auth.me()
Functions - WRONG vs CORRECT
❌ WRONG (hallucinated)
✅ CORRECT
functions.call('name', data)
functions.invoke('name', data)
functions.run('name', data)
functions.invoke('name', data)
callFunction('name', data)
functions.invoke('name', data)
httpsCallable('name')(data)
functions.invoke('name', data)
Integrations - WRONG vs CORRECT
❌ WRONG (hallucinated)
✅ CORRECT
ai.generate(prompt)
integrations.Core.InvokeLLM({prompt})
openai.chat(prompt)
integrations.Core.InvokeLLM({prompt})
llm(prompt)
integrations.Core.InvokeLLM({prompt})
sendEmail(to, subject, body)
integrations.Core.SendEmail({to, subject, body})
email.send()
integrations.Core.SendEmail({to, subject, body})
uploadFile(file)
integrations.Core.UploadFile({file})
storage.upload(file)
integrations.Core.UploadFile({file})
Exception: an OpenAI-compatible client (e.g. the Vercel AI SDK or the openai SDK) is correct when pointed at base44.asServiceRole.aiGateway.connection() — that's how you build code agents (agent loops with tools) and call the gateway's image, video, and speech endpoints. Use InvokeLLM only for a single call with no tools. See ai-gateway.md.
Actors - WRONG vs CORRECT
❌ WRONG (hallucinated)
✅ CORRECT
actors.connect('ChatRoom', roomId)
actors.ChatRoom(roomId).connect()
actors.ChatRoom.connect(roomId)
actors.ChatRoom(roomId).connect()
actors.ChatRoom(roomId).subscribe(cb)
subscribe on the connection: const conn = actors.ChatRoom(roomId).connect(); conn.subscribe(cb)
room.on('message', cb)
room.subscribe(cb) (one callback receives every message)
room.emit(data)
room.send(data)
new WebSocket(...) for app realtime
base44.actors.<Name>(id).connect()
const unsub = room.subscribe(cb); unsub()
const sub = room.subscribe(cb); sub.unsubscribe()
The two subscribe() methods return different shapes.Connection.subscribe() (actors) returns an object — sub.unsubscribe(). entities.<Name>.subscribe() returns the unsubscribe function itself — unsub(). Don't carry one convention to the other.
For client setup and authentication modes, see client.md.
TypeScript and type registries
Each reference file includes a "Type Definitions" section with TypeScript interfaces and types for the module's methods, parameters, and return values.
Getting typed entities, functions, actors, and agents: The Base44 CLI generates types from your project resources (entities, functions, actors, agents), including augmentations to EntityTypeRegistry, FunctionNameRegistry, ActorNameRegistry, and AgentNameRegistry, and wires them into your project so you get autocomplete and type checking without manual setup. For how to generate types, use the base44-cli skill.
Manual augmentation: You can instead augment the registries yourself in a .d.ts file; see the Type Definitions sections in entities.md, functions.md, actors.md, and base44-agents.md. Actor message types are always hand-authored — augment ActorRegistry so the actor and its clients share one definition.
Installation
Install the Base44 SDK:
npm install @base44/sdk
Important: Never assume or hardcode the @base44/sdk package version. Always install without a version specifier to get the latest version.
Creating a Client (External Apps)
When creating a client in external apps, ALWAYS use appId as the parameter name:
Chat with AI agents → agents (requires logged-in user)
Create new conversation → agents.createConversation()
Manage conversations → agents.getConversations()
Generate text/JSON with AI → integrations.Core.InvokeLLM()
Generate one image with default settings → integrations.Core.GenerateImage()
Several images, a specific model/aspect ratio/resolution, reference images, or edits → aiGateway images (see ai-gateway.md)
Generate a simple text-to-video → integrations.Core.GenerateVideo(); model choice, references, or frames → aiGateway videos, an async job (see ai-gateway.md)
Text-to-speech (TTS) or read-aloud → speech guide for browser/Core/gateway selection; read it before implementing model-specific controls or editing existing gateway speech code
Classify, score, or route a record against criteria → aiGateway with provider: "typesafe" (Jev), not InvokeLLM with a JSON schema (see ai-gateway.md)
Build a custom agent with tools (backend, agent SDK on the AI gateway) → aiGateway (see ai-gateway.md)
Custom backend logic?
Run server-side code → functions.invoke()
Need admin access → base44.asServiceRole.functions.invoke()
Realtime shared session?
Multiplayer, collaborative board/doc, presence, live cursors, in-room chat → actors.<Name>(roomId).connect() (see actors.md)
Just keeping a list of records live on screen → entities.EntityName.subscribe(), not an actor
const user = await base44.auth.me();
if (!user) {
// Navigate to your custom login page
navigate('/login', { state: { returnTo: window.location.pathname } });
return;
}
Backend Function Call
// Frontend
// ⚠️ invoke() returns the RAW axios response — your function's JSON is on `.data`,
// NOT the top-level object. It also THROWS on non-2xx (error body at err.response.data).
const res = await base44.functions.invoke("processOrder", {
orderId: "123",
action: "ship"
});
const result = res.data; // ✅ e.g. res.data.success (res itself is { data, status, headers, … })
// Backend function
import { createClientFromRequest } from "npm:@base44/sdk";
export default async function (req) {
const base44 = createClientFromRequest(req);
const { orderId, action } = await req.json();
// Process with service role for admin access
const order = await base44.asServiceRole.entities.Orders.get(orderId);
return Response.json({ success: true });
}
Realtime Room (Actor)
// Frontend — connect inside useEffect and always clean up
useEffect(() => {
const room = base44.actors.ChatRoom(roomId).connect();
const sub = room.subscribe((msg) => {
if (msg.type === "message") setMessages((prev) => [...prev, msg]); // switch on type; drop unknowns
});
return () => { sub.unsubscribe(); room.close(); }; // NOTE: actors return { unsubscribe() },
}, [roomId]); // entities.subscribe() returns the function itself
// Actor — base44/actors/ChatRoom/entry.ts
import { Actor } from "base44:runtime/actors";
export default class ChatRoom extends Actor {
handleConnect(conn) { conn.send({ type: "welcome" }); } // one client
handleMessage(conn, msg) {
// Always validate: the payload is attacker-controlled and msg can even be null.
if (msg?.type !== "message" || typeof msg.text !== "string") return;
this.broadcast({ type: "message", text: msg.text.slice(0, 2000) }); // everyone
}
handleClose(conn) {}
}
Service Role Access
Use asServiceRole in backend functions for admin-level operations. Actors expose this.client.asServiceRole for validated, room-owned work such as persisting canonical results; use verified conn.identity.userId from an authenticated connection for explicit user attribution. See actors.md.
// User mode - respects permissions
const myTasks = await base44.entities.Task.list();
// Service role - full access (backend only)
const allTasks = await base44.asServiceRole.entities.Task.list();
const token = await base44.asServiceRole.connectors.getAccessToken("slack");
Frontend vs Backend
Capability
Frontend
Backend
entities (user's data)
Yes
Yes
auth
Yes
Yes
agents
Yes
Yes
functions.invoke()
Yes
Yes
functions.fetch()
Yes
Yes
actors (connect to a room)
Yes
No — the actor is the server side
integrations
Yes
Yes
aiGateway
No
Yes
analytics
Yes
Yes
appLogs
Yes
Yes
users
Yes
Yes
asServiceRole.*
No
Yes
asServiceRole.connectors (app OAuth)
No
Yes
asServiceRole.sso
No
Yes
Backend functions export default an async request handler and use createClientFromRequest(req) to get a properly authenticated client.