API 기본 사항

Lovable API를 시작하는 데 필요한 기본 사항입니다.

기본 URL

기본 URL은 https://api.lovable.dev입니다. 엔드포인트는 /v1 아래에서 버전이 관리됩니다.

헤더

다음 표는 필수 및 선택 요청 헤더를 정리한 것입니다.

인증

요청은 워크스페이스 스코프 API 키로 인증합니다. 키는 Lovable-API-Key 헤더에 넣어 보내며 lov_로 시작합니다.

키는 Settings → Access tokens에서 만들고 관리합니다. 키를 만들려면 Business 또는 Enterprise 플랜과 워크스페이스 owner 또는 admin 역할이 필요합니다. 스코프, 만료, 크레딧 한도에 관한 자세한 내용은 API 키 만들기 및 관리를 참고하세요.

API를 호출하려면 Lovable 계정 이메일이 먼저 인증되어 있어야 합니다.

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

버전

요청을 특정 API 버전에 고정하려면 YYYY-MM-DD 형식의 버전 날짜를 Lovable-Version 헤더로 보냅니다.

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

헤더를 생략하면 가장 오래된 지원 안정 API 버전이 사용되며 현재 값은 2026-09-11입니다. 이 기본값은 API 전체에 적용되고 폐기된 버전은 건너뜁니다. 현재 기본 버전이 폐기될 때만 앞으로 이동하므로 업그레이드를 제어하려면 버전을 명시적으로 고정하세요.

안정 버전에 들어가기 전의 베타 기능을 시험하려면 선택 사항인 Lovable-Beta 헤더에 베타 리비전 문자열을 쉼표로 구분해 보냅니다. 베타 리비전은 요청한 안정 버전 위에 활성화됩니다. 요청이 베타 리비전을 선택하면 응답에는 적용된 리비전을 나열하는 Lovable-Beta 헤더가 포함됩니다. 현재 공개된 베타 리비전은 없습니다.

미디어 타입

JSON 본문이 있는 요청은 Content-Type: application/json을 사용합니다. GET 요청은 본문을 받지 않으므로 Content-Type 헤더가 필요 없습니다. 본문이 있는 응답은 application/json을 사용하며 XML이나 다른 표현은 지원하지 않습니다. 204 응답에는 본문이 없으므로 JSON으로 파싱하지 마세요. application/json을 제외하는 Accept 헤더를 보내면 406 응답이 반환됩니다. */*를 보내거나 헤더를 생략할 수도 있습니다.

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 메서드

HTTP 메서드는 작업의 일반적인 성격을 나타냅니다. 각 엔드포인트는 자체 응답 상태와 본문을 문서화합니다.

• GET: 리소스를 변경하지 않고 읽습니다. GET 요청은 안전하고 멱등적이며 요청 본문을 받지 않습니다.
• POST: 컬렉션에 리소스를 만들거나 문서화된 액션을 호출합니다. 임베드 URL 생성처럼 동기 액션은 200을 반환하고, 프로젝트 게시처럼 비동기 액션은 202를 반환합니다. POST 요청은 멱등성이 보장되지 않습니다. 이전 요청이 시간 초과되었거나 서버 오류를 반환했더라도 재시도하면 액션이 반복될 수 있습니다.
• PATCH: 기존 리소스를 부분 업데이트합니다. 변경하려는 필드만 보냅니다. 기존 리소스를 변경하는 기본 메서드이며 프로퍼티별 엔드포인트는 없습니다. 예를 들어 프로젝트 visibility를 변경하려면 전용 visibility 라우트를 호출하는 대신 PATCH /v1/projects/{project_id}에 {"visibility": "workspace_view"}를 보냅니다. 필드를 생략하면 그대로 유지됩니다. {"name": "New"}는 프로젝트 이름만 바꾸고 다른 값은 변경하지 않습니다.
• DELETE: 리소스를 제거합니다. 삭제에 성공하면 204를 반환합니다. 더 이상 존재하지 않는 리소스를 삭제하면 404가 반환될 수 있습니다.

API는 요청 본문을 엄격하게 검증합니다. 요청 본문의 알 수 없는 프로퍼티는 400 응답으로 거부됩니다. 알 수 없는 쿼리 매개변수 이름은 무시됩니다.

응답 코드

Lovable API는 표준 HTTP 코드를 사용해 요청의 성공 또는 실패를 나타냅니다.

오류 타입은 예시이며 완전한 목록이 아닙니다. 일부 엔드포인트는 project_not_found 또는 workspace_not_found 같은 리소스별 타입을 반환합니다.

오류 처리

모든 오류 응답은 같은 envelope를 사용합니다. 모든 필드는 항상 존재하며 detail, errors, props는 적용되지 않을 때 null입니다.

{
  "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: insufficient_scope 또는 rate_limited 같은 안정적인 snake_case 토큰입니다. 오류 처리는 문구가 바뀔 수 있는 title이 아니라 이 필드를 기준으로 분기하세요. 새 타입은 추가될 수 있으므로 알 수 없는 타입도 허용해야 합니다.
• title: 사람이 읽을 수 있는 요약입니다.
• status: HTTP 상태 코드를 그대로 담습니다.
• request_id: X-Request-Id 응답 헤더와 일치합니다. 지원팀에 문의할 때 포함하세요.
• detail: 이 오류 발생 건에 대한 설명입니다.
• errors: 필드 단위 검증 실패입니다. 각 항목에는 message와 location이 들어가며, 실패를 특정 필드에 연결할 수 없으면 location은 null입니다.
• props: 폐기된 버전의 migration_url처럼 오류 타입에 특화된 데이터입니다.

같은 HTTP 상태라고 해서 같은 진단 정보를 의미하지는 않습니다. 검증 실패는 type: invalid_request, detail: "validation failed", 조치 가능한 메시지가 담긴 errors와 함께 400을 반환합니다. 형식은 올바르지만 공개되지 않은 버전 날짜도 400을 반환하지만 type: unknown_version이고 detail과 errors는 null입니다.

속도 제한

API는 슬라이딩 윈도 속도 제한을 사용합니다. 제한을 평가할 수 있으면 응답에는 현재 상태를 알려 주는 헤더가 포함됩니다.

• X-RateLimit-Limit: 현재 윈도에서 허용되는 최대 요청 수입니다.
• X-RateLimit-Remaining: 현재 윈도에서 남은 요청 수입니다.
• X-RateLimit-Reset: 용량이 다시 사용 가능해지는 시각입니다. 지연 시간이 아니라 초 단위 절대 Unix timestamp입니다. 재설정 시각을 알 수 없으면 헤더가 없을 수 있습니다.

한도를 초과하면 API는 429 Too Many Requests를 반환합니다. API가 안전한 재시도 지연 시간을 계산할 수 있으면 응답에는 재시도 전 기다릴 초 수가 담긴 Retry-After 헤더도 포함됩니다.

각 API 키에는 자체 속도 제한이 있습니다. 세션 또는 OAuth 토큰으로 인증한 요청은 대신 해당 사용자의 대시보드 세션과 사용자 한도를 공유합니다. 일부 엔드포인트는 여기에 IP별, 워크스페이스별, 전역 버킷을 추가합니다. 헤더는 항상 요청에 적용되는 가장 빡빡한 버킷을 반영합니다.

API 버전을 고정해도 운영 속도 또는 동시성 할당량은 고정되지 않습니다. 페이로드 크기, 페이지 크기, 배치 크기처럼 유효한 요청에 대한 제한은 버전이 관리되는 계약에 남습니다.

윈도가 슬라이딩 방식이므로 X-RateLimit-Remaining은 고정된 재설정 시각에 한 번에 회복되는 대신 오래된 요청이 윈도에서 빠져나가면서 점진적으로 회복됩니다.

페이지네이션

목록 엔드포인트는 커서 기반 페이지네이션을 사용합니다. 결과를 제어하려면 다음 쿼리 매개변수를 보냅니다.

• limit: 페이지당 반환할 최대 항목 수입니다. 1부터 100까지 가능하며 기본값은 50입니다. 한 페이지에는 한도보다 적은 항목이 들어갈 수 있습니다.
• cursor: 이전 응답의 pagination.next_cursor에서 가져온 다음 페이지 커서입니다. 첫 요청에서는 생략합니다.

커서는 불투명 문자열입니다. HTTP 클라이언트의 쿼리 매개변수 지원으로 URL 인코딩하고, 다음 페이지를 따라갈 때 같은 필터, 정렬, 워크스페이스 선택을 유지하세요. 페이지네이션은 스냅샷을 제공하지 않으므로 동시 쓰기로 인해 뒤쪽 페이지의 내용이 바뀔 수 있습니다.

모든 목록 응답에는 data 배열과 pagination 객체가 포함됩니다.

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

• has_more: 현재 페이지 뒤에 결과가 더 있으면 true입니다.
• next_cursor: 다음 요청의 cursor로 전달할 값입니다. 더 이상 결과가 없으면 null입니다.

모든 결과를 가져오려면 has_more가 false가 될 때까지 다음 페이지를 계속 요청하세요. 존재하는 컬렉션에 일치하는 항목이 없으면 빈 data 배열과 함께 200을 반환합니다. 부모 리소스가 없으면 404가 반환될 수 있습니다.

읽기 일관성

일부 읽기는 최종적 일관성을 가지므로 최근 쓰기를 늦게 반영할 수 있습니다. 예를 들어 프로젝트와 멤버 목록, 워크스페이스 프로젝트 수, security insights의 프로젝트 및 멤버십 데이터가 여기에 해당합니다. 쓰기가 성공했다고 해서 이런 읽기가 변경 사항을 즉시 보여 주는 것은 아닙니다. 예상한 최근 변경이 보이지 않으면 백오프를 두고 읽기를 재시도하고 429 응답의 Retry-After를 지키세요. 레퍼런스의 엔드포인트 설명은 어느 읽기에 이 특성이 적용되는지 명시합니다.

크레딧 및 제한

Public API는 기존 프로젝트를 관리하고 배포합니다. 배포 빌드를 포함한 현재 엔드포인트는 AI 빌드 크레딧을 사용하지 않습니다. AI 프로젝트 생성 및 편집은 Lovable MCP 서버를 통해 사용할 수 있습니다. API 키를 만들 때 각 API 키가 한 달 동안 사용할 수 있는 AI 빌드 크레딧 상한을 설정할 수 있습니다. 상한은 매월 1일 00:00 UTC에 재설정됩니다.

FAQ

관련 주제

• 커스텀 커넥터 만들기
• 보안 개요
• LinkedIn에 앱 연결하기
• TikTok에 앱 연결하기
• 용어집