@lovable.dev/sdk

TypeScript SDK for the Lovable API.

Currently in preview.

Installation

npm install @lovable.dev/sdk

Usage

import { LovableClient } from "@lovable.dev/sdk";

const client = new LovableClient({
  apiKey: "lov_your-api-key",
});

// List workspaces
const workspaces = await client.listWorkspaces();
console.log(workspaces);

// Create a project
const project = await client.createProject(workspaces[0].id, {
  description: "A todo app with authentication",
  visibility: "private",
  initialMessage: "Create a simple todo app with user authentication",
});
console.log("Created project:", project.id);

// Wait for project to be ready (status = "completed")
const readyProject = await client.waitForProjectReady(project.id, {
  onProgress: (p) => console.log(`Status: ${p.status}`),
});

// Send a chat message to an existing project
await client.chat(readyProject.id, {
  message: "Add a dark mode toggle to the app",
});

// Wait for project to be published/deployed
const published = await client.waitForProjectPublished(project.id);
console.log("Live at:", published.url);

// Invite a collaborator to a workspace
await client.inviteCollaborator(workspaces[0].id, {
  email: "[email protected]",
  role: "member",
});

API Reference

LovableClient

Constructor

new LovableClient(options: LovableClientOptions)

• apiKey (required): Your Lovable API key
• baseUrl (optional): Override the default API base URL

Methods

listWorkspaces(): Promise<WorkspaceWithMembership[]>

List all workspaces the authenticated user has access to.

getWorkspace(workspaceId: string): Promise<WorkspaceWithMembership>

Get a specific workspace by ID.

listProjects(workspaceId: string, options?): Promise<ProjectResponse[]>

List projects in a workspace.

Options:

• limit (optional): Maximum number of projects to return
• visibility (optional): Filter by visibility ("all" | "personal" | "public" | "workspace")

createProject(workspaceId: string, options): Promise<ProjectResponse>

Create a new project in a workspace.

Options:

• description (required): Project description
• techStack (optional): Technology stack (e.g., "react")
• visibility (optional): Project visibility ("draft" | "private" | "public")
• templateProjectId (optional): ID of a template project to clone
• initialMessage (optional): Initial chat message to send to the AI agent

chat(projectId: string, options): Promise<void>

Send a chat message to a project's AI agent.

Options:

• message (required): The message to send
• chatOnly (optional): If true, only chat without making code changes

Note: This is an asynchronous operation. The API accepts the message and processes it in the background.

inviteCollaborator(workspaceId: string, options): Promise<WorkspaceMembershipResponse>

Invite a user to a workspace.

Options:

• email (required): Email address of the user to invite
• role (optional): Role to assign ("admin" | "collaborator" | "member" | "viewer")

listWorkspaceMembers(workspaceId: string): Promise<WorkspaceMembershipResponse[]>

List all members of a workspace.

removeWorkspaceMember(workspaceId: string, userId: string): Promise<void>

Remove a member from a workspace.

getProject(projectId: string): Promise<ProjectResponse>

Get project details by ID.

waitForProjectReady(projectId: string, options?): Promise<ProjectResponse>

Wait for a project to reach "completed" status. Projects start in "in_progress" status while being created/built.

Options:

• pollInterval (optional): Time between polls in ms (default: 2000)
• timeout (optional): Maximum time to wait in ms (default: 300000 = 5 minutes)
• onProgress (optional): Callback for status updates

Throws an error if the project fails or timeout is reached.

waitForProjectPublished(projectId: string, options?): Promise<ProjectResponse>

Wait for a project to be published (deployed) and have a live URL.

Options:

• pollInterval (optional): Time between polls in ms (default: 3000)
• timeout (optional): Maximum time to wait in ms (default: 600000 = 10 minutes)
• onProgress (optional): Callback for status updates

Throws an error if timeout is reached.

Types

The SDK exports TypeScript types for all API responses. See src/types.ts for the full list.

import type {
  WorkspaceWithMembership,
  ProjectResponse,
  CreateProjectOptions,
  // ... etc
} from "@lovable.dev/sdk";