API basics

Base URL

The base URL is https://api.lovable.dev. Endpoints are versioned under /v1.

Headers

The following table lists all required and optional request headers:

Header	Required	Description
`Lovable-API-Key`	Yes	Your workspace-scoped API key.
`Lovable-Version`	Recommended	The stable API version to serve, as a `YYYY-MM-DD` date. If you omit it, the API uses the oldest supported stable version.
`Accept`	No	Set to `application/json` or `/`, or omit the header. An `Accept` header that excludes `application/json` returns a `406` response.
`Content-Type`	No	Set to `application/json` on requests with a JSON body.
`Lovable-Beta`	No	Comma-separated beta revision strings to enable on top of the stable version.

Authentication

Requests authenticate with a workspace-scoped API key, sent in the Lovable-API-Key header. Keys start with lov_. You create and manage keys in Settings → Access tokens. Creating keys requires a Business or Enterprise plan, and an owner or admin role in the workspace. See Create and manage API keys for details on scopes, expiry, and credit limits. Your Lovable account email must be verified before you can call the API.

curl https://api.lovable.dev/v1/workspaces \
  -H "Lovable-API-Key: lov_YOUR_KEY"

Versions

Pin your requests to an API version by sending the Lovable-Version header with a version date in the YYYY-MM-DD format:

curl https://api.lovable.dev/v1/workspaces \
  -H "Lovable-API-Key: lov_YOUR_KEY" \
  -H "Lovable-Version: 2026-09-11"

If you omit the header, the request uses the oldest supported stable API version, which is currently 2026-09-11. This default is API-wide, skips retired versions, and advances only when the current default retires, so pin the version explicitly to control upgrades. To try beta functionality before it lands in a stable version, send the optional Lovable-Beta header with comma-separated beta revision strings. Beta revisions are enabled on top of the stable version you request. When a request selects beta revisions, the response includes a Lovable-Beta header listing the revisions that were applied. There are currently no beta revisions released.

Media types

Requests with JSON bodies use Content-Type: application/json. GET requests take no body and need no Content-Type header. Responses with bodies use application/json, and no XML or other representations are supported. A 204 response has no body, so do not parse it as JSON. Sending an Accept header that excludes application/json returns a 406 response. You can also send */* or omit the header.

curl https://api.lovable.dev/v1/workspaces \
  -H "Lovable-API-Key: lov_YOUR_KEY" \
  -H "Lovable-Version: 2026-09-11" \
  -H "Accept: application/json"

HTTP methods

HTTP methods indicate the general operation. Each endpoint documents its own response status and body:

GET: reads a resource without changing it. GET requests are safe, idempotent, and take no request body.
POST: creates a resource in a collection or invokes a documented action. A synchronous action returns 200, such as creating an embed URL, and an asynchronous action returns 202, such as publishing a project. POST requests are not guaranteed to be idempotent. Retrying may repeat the action, even if the previous request timed out or returned a server error.
PATCH: partially updates an existing resource. Send only the fields you want to change. This is the default method for changing existing resources, and there are no per-property endpoints. For example, to change a project’s visibility, send PATCH /v1/projects/{project_id} with {"visibility": "workspace_view"} instead of calling a dedicated visibility route. Omitting a field leaves it unchanged: {"name": "New"} renames the project and changes nothing else.
DELETE: removes a resource. A successful delete returns 204. Deleting a resource that no longer exists can return 404.

The API validates request bodies strictly. An unknown property in the request body is rejected with a 400 response. Unknown query parameter names are ignored.

Response codes

The Lovable API uses standard HTTP codes to indicate the success or failure of your requests.

Code	Error type	Description
`200`		Request succeeded.
`202`		Request accepted. Processing continues asynchronously.
`204`		Request succeeded with no response body.
`400`	`invalid_request`	The request body, parameters, or headers are malformed or fail validation. Each failing field is listed in the response with its location, such as `header.Lovable-Version`.
`400`	`unknown_version`	The date is not a released stable version.
`400`	`unknown_beta`	A beta string is not released.
`400`	`unsupported_beta_version`	A beta revision does not support the selected stable version.
`400`	`conflicting_betas`	Two revisions of one beta feature, or incompatible beta strings, were selected together.
`401`	`unauthorized`	Missing or invalid API key.
`402`	`payment_required`	Your workspace plan does not include this feature.
`403`	`insufficient_scope`	The API key lacks the scope this endpoint requires.
`403`	`forbidden`	The caller lacks the required permission.
`404`	`not_found`	The resource does not exist, is inaccessible to this key, or is unavailable under the endpoint’s documented prerequisites.
`406`	`not_acceptable`	The `Accept` header is incompatible with the endpoint’s media type.
`410`	`retired_version`	The selected stable version has retired. When provided, `props.migration_url` links to migration guidance.
`410`	`retired_beta`	A beta revision has retired. When provided, `props.migration_url` links to migration guidance.
`429`	`rate_limited`	Rate limit exceeded. Retry after the interval in the `Retry-After` header when present.
`503`	`no_supported_version`	No stable version is currently supported.
`5xx`		Server error. Usually transient, so retry reads with backoff. A POST may have already taken effect, so retry it with care.

The error types are examples, not an exhaustive list. Some endpoints return resource-specific types instead, such as project_not_found or workspace_not_found.

Error handling

Every error response uses the same envelope. All fields are always present, and detail, errors, and props are null when they do not apply:

{
  "type": "invalid_request",
  "title": "Bad Request",
  "status": 400,
  "request_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "detail": "validation failed",
  "errors": [
    {
      "location": "body.members",
      "message": "expected array length >= 1"
    }
  ],
  "props": null
}

type: a stable snake_case token, such as insufficient_scope or rate_limited. Branch your error handling on this field, not on title, whose wording can change. New types are additive, so tolerate types you do not recognize.
title: a human-readable summary.
status: echoes the HTTP status code.
request_id: matches the X-Request-Id response header. Include it when contacting support.
detail: explains this specific occurrence.
errors: field-level validation failures. Each entry contains a message and a location, and location is null when the failure cannot be attributed to a field.
props: data specific to the error type, such as migration_url on retired versions.

The same HTTP status does not imply the same diagnostics. A validation failure returns 400 with type: invalid_request, detail: "validation failed", and actionable messages in errors. A well-formed but unreleased version date also returns 400, but with type: unknown_version and detail and errors set to null.

Rate limits

The API uses sliding-window rate limits. When a limit could be evaluated, responses include headers that tell you where you stand:

X-RateLimit-Limit: the maximum number of requests allowed in the current window.
X-RateLimit-Remaining: how many requests you have left in the current window.
X-RateLimit-Reset: when capacity next becomes available, as an absolute Unix timestamp in seconds, not a delay. The header can be absent when the reset time is unknown.

If you exceed your limit, the API returns 429 Too Many Requests. When the API can calculate a safe retry delay, the response also includes a Retry-After header with the number of seconds to wait before retrying. Each API key has its own rate limit. Requests authenticated with a session or OAuth token share the user’s limit with dashboard sessions instead. Some endpoints add per-IP, per-workspace, or global buckets on top. The headers always reflect the most constrained bucket that applies to your request. Pinning an API version does not pin operational rate or concurrency quotas. Limits on a valid request, such as payload size, page size, and batch size, remain part of the versioned contract. Because the window is sliding, X-RateLimit-Remaining recovers gradually as older requests age out rather than all at once at a fixed reset time.

Pagination

List endpoints use cursor-based pagination. Pass these query parameters to control the results:

limit: the maximum number of items to return per page, from 1 to 100. Defaults to 50. A page can contain fewer items than the limit.
cursor: the cursor for the next page, taken from pagination.next_cursor in the previous response. Omit this on the first request.

Cursors are opaque strings. URL-encode them with your HTTP client’s query parameter support, and keep the same filters, sorting, and workspace selection when following pages. Pagination does not provide a snapshot, so concurrent writes can change what later pages contain. Every list response includes a data array and a pagination object:

{
  "data": [
    { "id": "..." }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "..."
  }
}

has_more: true when there are more results beyond the current page.
next_cursor: the cursor to pass in your next request. null when there are no more results.

To fetch all results, keep requesting the next page until has_more is false. A collection that exists but has no matching items returns 200 with an empty data array. A missing parent resource can return 404.

Read consistency

Some reads are eventually consistent and can lag recent writes, for example project and member lists, workspace project counts, and project and membership data in security insights. A successful write does not guarantee that these reads immediately reflect the change. If an expected recent change is missing, retry the read with backoff and honor Retry-After on 429 responses. The endpoint descriptions in the reference state which reads this applies to.

Credits and limits

The public API manages and deploys existing projects. Its current endpoints, including deployment builds, do not consume AI build credits. AI project creation and editing are available through the Lovable MCP server. You can cap how many AI build credits each API key can spend per calendar month when you create the key. The cap resets at 00:00 UTC on the first day of each month.

FAQ

Where do I get a Lovable API key?

Create one from Settings → Access tokens. You need a Business or Enterprise workspace and an owner or admin role.

Which headers should I use?

Only Lovable-API-Key, with the API key you copied from Lovable, is required. Pinning Lovable-Version to an API version date is recommended to control upgrades. Set Content-Type: application/json on requests with a JSON body. See Headers for details and examples.

Can I use the key in browser code?

No. Use Lovable API keys only from trusted server-side code, scripts, or automation tools.

Why can't I create or build projects with the Lovable API?

The public API manages and deploys existing projects, including deployment builds through the publish endpoint. It does not expose AI project creation or editing. Use the Lovable MCP server to build out projects with AI from a client such as Claude or Cursor.

Get started

API changelog

Endpoints

Base URL

Headers

Authentication

Versions

Media types

HTTP methods

Response codes

Error handling

Rate limits

Read consistency

Credits and limits

FAQ

​Base URL

​Headers

​Authentication

​Versions

​Media types

​HTTP methods

​Response codes

​Error handling

​Rate limits

​Pagination

​Read consistency

​Credits and limits

​FAQ

Base URL

Headers

Authentication

Versions

Media types

HTTP methods

Response codes

Error handling

Rate limits

Pagination

Read consistency

Credits and limits

FAQ