@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();

// 1. Create a project
const project = await client.createProject(workspaces[0].id, {
  description: "Best todo app",
  initialMessage: "Create a todo app with authentication"
});

// 2. Wait for the AI response and get the preview URL
const response = await client.waitForResponse(project.id);
console.log(response.content);    // AI's response text
console.log(response.previewUrl); // Preview URL for the project

// 3. Send a follow-up chat message
await client.chat(project.id, {
  message: "Add a footer",
});

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. Use waitForResponse() to wait for the AI's reply.

waitForResponse(projectId: string, options?): Promise<ChatResponse>

Wait for the AI's response to a chat message. Connects to the project's message stream (SSE) and returns the full response once complete.

Use this after chat() or after createProject() with initialMessage.

Returns:

• content (string): The AI's full response text
• previewUrl (string): The project's preview URL

Options:

• timeout (optional): Maximum time to wait in ms (default: 300000 = 5 minutes)

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

getPreviewUrl(projectId: string): string

Get the preview URL for a project. This is a synchronous method that constructs the URL from the project ID.

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";