프로젝트를 빌드하고 배포합니다.
프로젝트 게시
플랜:
Business 이상
스코프: projects:write
프로젝트를 빌드하고 배포합니다. 이 엔드포인트는 202와 Deployment 표현을 반환합니다. 처음 상태는 running이고 url 및 오류 필드는 null입니다. 배포가 끝날 때까지 GET /v1/projects/{project_id}/publish/{deployment_id}를 poll하세요.
필요하면 audience로 게시된 앱을 열 수 있는 대상을 선택할 수 있습니다. 프로젝트 읽기 응답에서는 이 값이 publish_audience로 보고됩니다. audience를 생략하면 현재 설정을 유지합니다. audience 변경은 새 배포가 끝나기 전에 현재 게시된 버전에 즉시 적용됩니다. 앱을 다시 빌드하지 않고 접근 설정만 바꾸려면 PATCH /v1/projects/{project_id}/publish를 사용합니다. 앱을 오프라인으로 전환하려면 DELETE /v1/projects/{project_id}/publish를 사용합니다.
OpenAPI
| 항목 | 값 |
|---|---|
| Method | POST |
| Path | /v1/projects/{project_id}/publish |
| Operation ID | publishProject |
| Source spec | https://api.lovable.dev/v1/openapi.yaml |
| Local snapshot | YAML 스냅샷 (SHA-256: 409e545e8b27237e241ac8cadd7f177f11cab6f2b6146d69d6a712ee7855ba6a) |
POST /v1/projects/{project_id}/publish인증
Lovable-API-Key: lov_your-api-key 또는 Authorization: Bearer <key>를 보냅니다. 이 엔드포인트는 projects:write 스코프가 필요합니다.
매개변수
| 이름 | 위치 | 필수 | 타입 | 설명 |
|---|---|---|---|---|
project_id | path | 예 | string | 프로젝트 ID입니다. |
Lovable-Version | header | 아니요 | string | 제공받을 안정 API 버전입니다. YYYY-MM-DD 날짜 형식으로 보냅니다. 생략하면 현재 가장 오래된 지원 안정 버전인 2026-09-11이 사용됩니다. |
Lovable-Beta | header | 아니요 | string | 안정 버전 위에 활성화할 베타 리비전 문자열입니다. 여러 개는 쉼표로 구분합니다. |
요청 본문
요청 본문은 필수입니다. Content-Type은 application/json입니다. 본문은 PublishProjectRequest 스키마를 사용합니다.
| 필드 | 타입 | 필수 | 설명 | 예시 |
|---|---|---|---|---|
name | string | 아니요 | 관리형 게시 URL의 slug입니다. 예를 들어 acme-landing-page는 https://acme-landing-page.lovable.app을 만듭니다. 커스텀 도메인과 워크스페이스 브랜딩은 hostname을 바꿀 수 있습니다. | acme-landing-page |
audience | string | 아니요 | 게시된 앱을 열 수 있는 대상입니다. public, workspace, custom 중 하나입니다. 프로젝트 읽기 응답에서는 publish_audience로 보고됩니다. UI에서 관리하는 기존 grant를 포함한 custom audience를 사용할 수 있습니다. 생략하면 현재 설정을 유지합니다. | custom |
audience_targets | PublishAudienceTarget[] | 아니요 | 앱을 열 수 있는 그룹입니다. audience가 custom일 때만 허용됩니다. 목록을 제공하면 모든 그룹 및 사용자 grant를 대체하고 워크스페이스 전체 접근을 제거합니다. 빈 목록은 해당 grant를 제거합니다. UI에서 관리하는 기존 조직 접근과 이메일 초대는 보존됩니다. 생략하면 audience 변경 중에도 저장된 target을 유지합니다. custom 모드 밖에서는 target이 비활성입니다. null은 허용되지 않습니다. 최대 100개까지 보낼 수 있습니다. | [{"id":"grp_01jw3k9m2xq8r5v0c7d4e6f2gh","type":"group"}] |
PublishProjectRequest는 위 표의 name, audience, audience_targets만 받습니다. 스키마에 선언되지 않은 필드를 함께 보내면 요청이 거부됩니다(additionalProperties: false).
PublishAudienceTarget은 type과 id를 필수로 가집니다. 현재 type은 group만 지원하며 id는 GET /v1/workspaces/{workspace_id}/groups가 반환한 그룹 ID입니다. id는 빈 문자열일 수 없으며(minLength: 1), audience_targets는 최대 100개까지 보낼 수 있습니다.
예시
curl --request POST \
--url 'https://api.lovable.dev/v1/projects/project-id/publish' \
--header 'Lovable-API-Key: lov_your-api-key' \
--header 'Lovable-Version: 2026-09-11' \
--header 'Content-Type: application/json' \
--data '{}'const response = await fetch("https://api.lovable.dev/v1/projects/project-id/publish", {
method: "POST",
headers: {
"Lovable-API-Key": process.env.LOVABLE_API_KEY ?? "lov_your-api-key",
"Lovable-Version": "2026-09-11",
"Content-Type": "application/json",
},
body: JSON.stringify({}),
});
if (!response.ok) {
throw new Error(`Lovable API ${response.status}: ${await response.text()}`);
}
console.log(await response.json());응답
| 상태 | 본문 | 설명 |
|---|---|---|
202 | Deployment | 배포가 시작되었습니다. 반환된 id를 사용해 Location 헤더의 GET /v1/projects/{project_id}/publish/{deployment_id}를 poll합니다. |
400 | ErrorResponse | 요청 본문 또는 매개변수 형식이 잘못되었거나 검증에 실패했습니다. 실패한 각 필드는 errors에 나열됩니다. |
401 | ErrorResponse | API 키, 세션 토큰 또는 OAuth access token이 없거나 유효하지 않습니다. |
402 | ErrorResponse | Public API 접근에는 Business 이상 플랜이 필요합니다. 일부 작업이나 구성에는 추가 기능 권한이 필요합니다. |
403 | ErrorResponse | 키 또는 호출자에게 필요한 스코프나 권한이 없습니다. email_not_verified인 경우 계정 이메일을 인증한 뒤 다시 시도하세요. |
404 | ErrorResponse | 프로젝트가 존재하지 않거나 삭제되었거나 인증된 클라이언트가 접근할 수 없습니다. |
406 | ErrorResponse | Accept 헤더가 이 엔드포인트가 생성하는 모든 미디어 타입을 제외합니다. |
429 | ErrorResponse | 요청이 너무 많습니다. Retry-After가 있으면 해당 간격 뒤에 재시도합니다. |
503 | ErrorResponse | 서비스를 일시적으로 사용할 수 없거나 처리 기한이 만료되었습니다(request_timeout). 변이가 완료될 수 있으므로 재시도 전에 리소스 상태를 확인하세요. |
default | ErrorResponse | 오류입니다. 응답 본문은 표준 오류 envelope을 사용하며 status는 HTTP 상태 코드와 같고 type은 machine-readable 오류 코드입니다. |
오류 요구사항 metadata
게시는 쓰기 작업이므로 요구사항 metadata는 402와 403 응답의 props에만 담깁니다. 402 payment_required는 최소 플랜 tier를 담은 required_plan을 주거나, 기능 게이트일 때 required_features 배열을 주며 required_features의 식별자는 '모두' 충족해야 합니다. 두 key는 함께 오지 않으며 결제 실패에 따라 둘 다 없을 수 있습니다. 403 forbidden의 required_permissions는 대체 가능한 권한 집합의 배열이고 어느 한 집합의 권한을 '모두' 가지면 통과하므로 'AND 집합들의 OR'로 읽습니다. 403 insufficient_scope의 required_scopes는 허용되는 스코프 목록이며 그중 '아무거나' 하나로 충족됩니다. 게시에는 projects:write가 그 목록에 해당하므로 projects:read만 가진 키는 insufficient_scope를 받습니다.
type | props 구조와 의미 |
|---|---|
payment_required | 플랜 게이트는 최소 tier(pro, business, enterprise)를 담은 required_plan을 포함합니다. 기능 게이트는 대신 기능 권한 식별자 배열인 required_features를 포함하며 배열의 모든 항목이 필요합니다. 예를 들어 {"required_plan":"business"}입니다. 다른 결제 실패는 둘 다 없을 수 있습니다. |
forbidden | 권한 게이트는 대체 가능한 권한 집합의 배열인 required_permissions를 포함합니다. 한 집합의 권한을 모두 가지면 그 게이트를 충족합니다. 예를 들어 [["project:edit"]]는 해당 권한을 요구하고 [["a","b"],["c"]]는 a와 b를 모두 가지거나 c를 가질 것을 요구합니다. 다른 거부에는 요구사항 metadata가 없을 수 있습니다. |
insufficient_scope | required_scopes는 허용되는 자격 증명 스코프의 배열이며 그중 하나만 있으면 실패한 스코프 검사를 충족합니다. 쓰기 스코프는 대응하는 읽기 스코프도 포함합니다. 예를 들어 {"required_scopes":["projects:write"]}입니다. |
security_critical_findings | finding_refs는 게시를 막는 보안 발견 항목을 식별하는 문자열 배열입니다. 예를 들어 {"finding_refs":["supabase/finding-1"]}입니다. |
retired_version, retired_beta | migration_url은 마이그레이션 가이드로 연결되는 문자열 URL이며 제공 가능한 경우에만 포함됩니다. |
요구사항 metadata는 실패한 검사만 설명하며 작업의 모든 조건을 설명하지 않습니다. 다른 검사가 여전히 요청을 거부할 수 있고 metadata 자체가 생략될 수도 있습니다. 권한·기능 식별자는 실질적 접근 범위를 설명하며 필요한 워크스페이스 역할을 확정하지 않으므로 접근 권한이 필요하면 워크스페이스 관리자에게 문의하세요. 식별자는 시간이 지나며 추가될 수 있습니다. 내부 전용 요구사항과 리소스를 감추는 응답은 접근 요구사항을 공개하지 않습니다.
응답 헤더
모든 응답에는 상황에 따라 다음 공통 헤더가 포함될 수 있습니다: Lovable-Version, Lovable-Beta, X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Lovable-Unknown-Query-Params, X-Lovable-Unknown-Query-Params-Omitted. X-Lovable-Unknown-Query-Params는 이 작업이 선언하지 않은 query parameter가 있을 때 URL escape된 이름을 최대 20개까지 쉼표로 제공하며, 20개를 넘으면 X-Lovable-Unknown-Query-Params-Omitted가 누락된 개수(minimum: 1)를 제공합니다. 401 응답은 string인 WWW-Authenticate를, 429 응답은 integer인 Retry-After를 포함합니다. Retry-After는 minimum: 1입니다. X-RateLimit-Reset은 지연 시간이 아니라 Unix timestamp 초 단위입니다.
POST /v1/projects/{project_id}/publish의 202 응답은 추가로 string인 Location 헤더를 제공하며, 이 값은 반환된 deployment 상태를 poll할 GET /v1/projects/{project_id}/publish/{deployment_id} URL입니다.
스키마
PublishAudienceTarget
| 필드 | 타입 | 필수 | 제약 | 설명 | 예시 |
|---|---|---|---|---|---|
type | string | 예 | enum: group | 대상 유형입니다. 현재 그룹만 설정할 수 있습니다. | group |
id | string | 예 | minLength: 1 | GET /v1/workspaces/{workspace_id}/groups가 반환한 그룹 ID입니다. | grp_01jw3k9m2xq8r5v0c7d4e6f2gh |
PublishAudienceTarget은 type과 id 외의 필드를 받지 않습니다. 스키마에 선언되지 않은 필드가 포함된 target이 있으면 요청이 거부됩니다(additionalProperties: false).
Deployment 응답 스키마는 게시 상태 조회와 같습니다. id, status, url, error_message, error_class는 모두 필수 필드입니다. status는 running, completed, error, unknown 값을 사용할 수 있으며 클라이언트는 새 값을 허용해야 합니다. url, error_message, error_class는 값이 없으면 null입니다. error_class는 transient, code, configuration, data, integration, policy, internal, null 중 하나이며 새 값이 추가될 수 있습니다.
ErrorResponse
공통 오류 응답입니다. 작업에 따라 특정 상태 코드에 다른 응답 본문이 문서화될 수 있습니다.
| 필드 | 타입 | 필수 | 설명 | 예시 |
|---|---|---|---|---|
detail | `string \ | null` | 예 | 이번 오류에 대한 사람이 읽을 수 있는 안내입니다. 적용되지 않으면 null입니다. invalid_request에서는 validation failed이며 실행 가능한 필드 메시지는 errors에 있습니다. |
errors | `array \ | null` | 예 | 검증 실패 시 필드 단위 오류 상세 정보입니다. 필드 단위 상세 정보가 적용되지 않으면 null입니다. 각 항목은 location과 message를 담으며 실패를 특정 필드에 귀속할 수 없으면 location이 null입니다. |
props | `object \ | null` | 예 | 오류별 metadata입니다. 적용되지 않으면 null입니다. key는 type에 따라 달라지며 인식하지 못한 key는 무시하세요. |
request_id | string | 예 | X-Request-Id 응답 헤더에서 반복되는 이 요청의 식별자입니다. | 4bf92f3577b34da6a3ce929d0e0e4736 |
status | integer | 예 | 본문에 반복되는 HTTP 상태 코드입니다. | 429 |
title | string | 예 | 사람이 읽을 수 있는 오류 요약입니다. 문구는 바뀔 수 있으므로 오류 처리는 type을 기준으로 결정하세요. | Too Many Requests |
type | string | 예 | 안정적인 machine-readable 오류 유형입니다. URI가 아니라 rate_limited 같은 snake_case token입니다. | rate_limited |
원본에 포함된 이 작업의 OpenAPI 스냅샷은 YAML 스냅샷 (SHA-256: 409e545e8b27237e241ac8cadd7f177f11cab6f2b6146d69d6a712ee7855ba6a)로 보존했습니다. 최신 전체 OpenAPI 계약은 https://api.lovable.dev/v1/openapi.yaml에서 확인할 수 있습니다.