비즈니스 데이터 업로드

이 기능의 위치

데이터 업로드를 통해 Kaleidr는 조직 자체 데이터를 기반으로 질문에 답변할 수 있습니다. 이는 Enterprise 기능입니다. 게시된 업로드 데이터는 로그인한 구성원을 위한 Kaleidr Studio의 AI 어시스턴트에 사용됩니다. 자체 사이트 또는 백엔드에서 이용하려면 데이터를 읽을 수 있는 키 발급, 해당 키로 질문하기, 답변에 등록한 장소가 나타나는지 확인하기의 세 단계가 더 필요합니다. 자체 데이터로 답변하기에는 전체 과정과 업로드 데이터를 답변에 활용하는 방식이 설명되어 있습니다. 이 문서는 업로드 단계의 모든 요청, 필드, 제한, 오류 및 게시 버전의 철회 방법을 다룹니다.

이 문서는 Kaleidr Studio의 데이터 패널에서 지도에 추가하는 파일(스프레드시트, GeoJSON 파일, GPX 경로)을 다루지 않습니다. 이는 모든 요금제에서 제공되는 별도 기능입니다. 지도의 데이터세트를 참조하세요.

업로드는 다음 두 방법으로 가능하며, 둘 다 동일한 처리 파이프라인을 사용합니다.

화면에서: Kaleidr Studio의 어느 지도에서나 데이터 패널 하단의 Data for AI Answers 섹션을 사용합니다. 유일한 업로드 화면이며, 권한이 있는 조직 소유자 또는 관리자에게만 업로드 컨트롤이 나타납니다. Kaleidr Studio에서 업로드하기를 참고하세요.
이 페이지의 API에서: 화면도 동일한 API를 호출하므로 아래의 파일 형식, 제한, 상태 및 오류는 두 방법 모두에 적용됩니다. 한쪽에서 만든 릴리스는 다른 쪽에서도 확인할 수 있습니다.

업로드를 시작하기 전에 알아야 할 세 가지 특징은 다음과 같습니다.

질문에 답할 때 데이터를 조회합니다. Kaleidr는 그 시점에 게시된 릴리스를 참조하므로 게시를 취소하면 이후 답변에서 해당 데이터가 즉시 사용되지 않습니다.
데이터는 해당 조직에만 제공됩니다. 조직별로 분리되어 있으며 Kaleidr 소비자용 지도나 다른 조직의 답변에 나타나지 않습니다.
값을 임의로 생성하지 않습니다. 선택적 도우미가 헤더 행과 최대 5개 샘플 행으로 열 매핑을 제안할 수 있습니다. 이후 승인한 매핑으로 파일의 모든 행을 변환합니다. 잘못된 매핑은 수정한 후 다시 실행해야 하며, 가격·날짜·이름을 만들어 넣지 않습니다.

이용 가능 조건

요구 사항	세부 정보
요금제	Enterprise. Free 및 Pro에서는 업로드, 게시, 재실행, 매핑 제안 호출이 403 `vendor_data_not_on_plan`을 반환합니다. 적용되는 요금제는 kaleidr.com/billing에서 구매하거나 변경하는 조직의 Kaleidr 요금제이며, Studio에는 별도 요금제가 없습니다.
역할	조직 소유자 또는 관리자만 가능합니다. 그 외에는 403 `org_admin_required`입니다.
제한	조직 계약에서 정하며 제한을 참조하세요. `GET /shared-api/datahub/limits`로 조직별 실제 한도를 조회합니다.
인터페이스	Kaleidr Studio의 데이터 패널에 있는 Data for AI Answers 섹션 또는 이 페이지의 API입니다. 같은 파이프라인과 검증을 사용합니다.

어떤 API 호출에 어떤 요금제가 필요한가요?

호출	역할	요금제
매핑 제안, 업로드, 게시, 재실행	소유자 또는 관리자	Enterprise
한도, 수집 작업 상태, 릴리스 목록 조회	소유자 또는 관리자	모두
릴리스 게시 취소 및 삭제	소유자 또는 관리자	모두

두 번째 및 세 번째 행의 작업은 모든 요금제에서 계속 사용할 수 있습니다. 따라서 업로드가 불가능한 요금제로 변경한 조직도 기존 업로드를 확인하고 철회할 수 있습니다.

데이터 활용도 두 사용 위치 모두 Enterprise에서만 가능합니다. 조직이 Enterprise일 때만 Kaleidr Studio의 어시스턴트가 게시된 릴리스에 근거해 답변합니다. API 키 또는 SDK를 통해 답변에 데이터를 포함하려면 Enterprise 조직에만 부여되는 별도 권한인 vendor 범위가 필요합니다. 자체 데이터로 답변하기를 참조하세요.

Studio의 Data for AI Answers 섹션에 표시되는 내용은 조직 요금제와 사용자 역할에 따라 달라집니다. 자세한 내용은 업로드할 수 없을 때 표시되는 내용을 참조하세요.

조직의 업로드 가능 범위

업로드 전에 조회하세요. Studio가 이 섹션을 열 때 읽는 API입니다.


요청	`GET /shared-api/datahub/limits`
권한	모든 요금제의 소유자 또는 관리자
쿼리	여러 조직을 관리하는 경우 조직을 선택하는 선택적 `org_id`

curl https://api.kaleidr.com/shared-api/datahub/limits \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

이 예시는 Enterprise 조직을 대상으로 합니다. 세 가지 한도는 조직 계약에 따라 달라 실제 값처럼 제시할 수 없으므로 예시에서 의도적으로 생략했습니다. limits에는 아래 표의 세 정수 필드가 항상 있습니다.

{
  "can_upload": true,
  "plan": "enterprise",
  "limits": { "…": "places, documents and artifact_mb: three integers, described below" },
  "reason": null
}

Free 및 Pro에서도 호출은 사유와 함께 200을 반환합니다.

{
  "can_upload": false,
  "plan": "pro",
  "limits": { "places": 0, "documents": 0, "artifact_mb": 0 },
  "reason": "vendor_data_not_on_plan"
}

필드	유형	의미
`can_upload`	불리언	해당 조직의 업로드를 허용하는지 여부
`plan`	문자열 또는 null	한도를 정의하는 요금제: `free`, `pro`, `enterprise`
`limits.places`	정수	업로드 한 번에 허용되는 장소 수. CSV에서는 데이터 행 수
`limits.documents`	정수	업로드 한 번에 허용되는 문서 수
`limits.artifact_mb`	정수	파일의 MiB 단위 크기
`reason`	문자열 또는 null	`can_upload`가 `false`이면 `vendor_data_not_on_plan`, 그렇지 않으면 `null`. 이때 모든 한도는 0입니다.

이 수치는 조직의 계약에 따라 정해집니다. 단, 어떤 한도도 플랫폼 자체에서 허용하는 업로드 상한을 초과할 수 없습니다. 플랫폼은 세 항목마다 기술적인 상한을 두고 있으며 계약으로도 이를 높일 수 없습니다.

상태	의미
200	모든 요금제에서 소유자 또는 관리자에게 반환합니다. Enterprise 미만에서는 거부 응답 대신 `can_upload: false`가 반환됩니다.
401	액세스 토큰이 없거나 만료되었거나 올바른 액세스 토큰이 아닙니다.
403 `org_admin_required`	계정이 조직 소유자 또는 관리자가 아닙니다.

인증

모든 요청에서 로그인한 Kaleidr 계정의 액세스 토큰을 Bearer 토큰으로 전달합니다.

Authorization: Bearer <account access token>

API 키가 아닙니다. kld_pk_… 또는 kld_sk_… 키는 거부됩니다. 키는 통합을 식별하고 데이터 업로드는 조직 관리 작업이므로 적절한 역할을 가진 사용자로 인증해야 합니다.
ID 토큰이 아닌 액세스 토큰이어야 합니다.
로그인한 조직 소유자 또는 관리자에게 발급되며 로그인 세션과 함께 만료됩니다. 이 API에는 아직 장기 유효 자격 증명이 없습니다. 자동화 작업으로 업로드하려면 구현 전에 Kaleidr에 문의하세요.
Studio 화면은 로그인한 구성원의 세션을 사용하므로 직접 토큰을 처리할 필요가 없습니다.

이 페이지의 모든 경로는 https://api.kaleidr.com을 기준으로 합니다. 예시는 환경 변수에서 토큰을 읽습니다.

export KALEIDR_ACCESS_TOKEN='<account access token>'

여러 조직을 관리한다면 org_id를 추가하세요(업로드 요청 본문 또는 다른 호출의 ?org_id= 쿼리 매개변수). 생략하면 기본 조직이 선택됩니다.

업로드할 수 있는 데이터

업로드 한 번은 텍스트 파일 하나를 JSON 요청의 문자열로 전송합니다. 파일명 확장자에 따라 파싱 방식이 결정됩니다.

데이터	전송 형식	포함 내용
장소 목록	고정 열 이름을 사용하는 매핑 없는 `.csv`	장소
숙박일, 객실 또는 요금별 한 행을 가진 스프레드시트 내보내기	`.csv`와 `mapping_spec`	장소, 객실 유형, 요금제, 일별 요금, 재고
이미 구조화된 전체 데이터	`.json` 묶음	위 항목과 영업시간 및 문서

모든 업로드에는 장소가 최소 한 개 포함되어야 합니다.

장소 CSV

헤더 행에는 다음 열 이름을 사용합니다.

열	필수	설명
`name`	예	이름이 없는 행은 업로드가 실패하며 행 번호가 보고됩니다.
`timezone`	예	`Europe/London` 같은 IANA 시간대
`lat`, `lng`	두 형태 중 하나	입력한 그대로 사용하는 좌표
`address`	두 형태 중 하나	`lat`, `lng`가 없으면 좌표를 찾는 데 사용
`category`	아니요	`hotel` 또는 `restaurant` 같은 짧은 범주
`ref`	아니요	행에 부여한 자체 식별자. 없으면 행 번호를 사용

name,timezone,lat,lng,address,category
Harbor Hotel,Europe/London,51.5079,-0.0877,"1 Example Street, London",hotel
Canal House,Europe/Amsterdam,,,"Example Gracht 12, Amsterdam",hotel

열 매핑이 있는 시트

부동산·객실·요금제·날짜·가격 등 관측값 하나마다 행이 있는 시트는 고정 열 이름만으로 읽을 수 없습니다. 각 필드에 사용할 열을 지정한 mapping_spec과 함께 전송하세요.

Property,Address,Room,Plan,Date,Nightly Rate,Available
Harbor Hotel,"1 Example Street, London",Double,Flexible,2026-11-06,189.00,4
Harbor Hotel,"1 Example Street, London",Suite,Flexible,2026-11-06,320.00,1

{
  "places": {
    "ref_from": ["Property"],
    "fields": {
      "name": "Property",
      "address": "Address",
      "timezone": { "const": "Europe/London" },
      "category": { "const": "hotel" }
    }
  },
  "room_types": { "ref_from": ["Room"], "fields": { "name": "Room" } },
  "rate_plans": { "ref_from": ["Plan"], "fields": { "name": "Plan" } },
  "daily_rates": {
    "fields": {
      "stay_date": "Date",
      "price_amount": "Nightly Rate",
      "price_currency": { "const": "GBP" }
    }
  },
  "daily_inventory": {
    "fields": { "stay_date": "Date", "units_available": "Available" }
  }
}

매핑 규칙:

항목	의미
섹션	`places`(필수), `room_types`, `rate_plans`, `daily_rates`, `daily_inventory`. 시트에 실제로 있는 데이터의 섹션만 포함합니다.
`ref_from`	한 항목을 식별하는 열. 해당 열들의 값이 같으면 같은 장소·객실 유형·요금제입니다.
`fields`	각 필드는 열 이름을 통해 값을 공급받습니다. 일부 필드는 `{ "const": "value" }` 형태의 상수도 허용합니다.

매핑은 아래 표의 필드만 설정할 수 있습니다. 마지막 열은 상수를 허용하는 필드입니다.

섹션	매핑으로 설정 가능한 필드	상수 허용
`places`	`name`, `address`, `timezone`, `category`, `lat`, `lng`, `overture_id`	`timezone`, `category`
`room_types`	`name`	`name`
`rate_plans`	`name`, `currency`, `cancellation_policy`, `board_basis`	`name`, `currency`
`daily_rates`	`stay_date`(ISO 날짜), `price_amount`(0 이상의 숫자), `price_currency`(세 글자)	`price_currency`
`daily_inventory`	`stay_date`, `units_available`(0 이상의 정수)	없음

다음 두 규칙 중 하나라도 위반하면 검증 오류입니다.

표에 없는 필드는 거부됩니다. 오류에는 해당 필드와 허용된 필드가 표시됩니다. room_types.fields.beds: not a field a mapping can set -- room_types takes name. 침대 수나 임의 속성처럼 시트 셀에서 매핑할 수 없는 값은 대신 JSON 묶음으로 전송합니다.
다른 위치에서 상수를 사용하면 거부됩니다. 가격, 날짜, 수량, 장소 이름 및 위치는 파일의 열에서 가져와야 합니다. daily_rates.fields.price_amount: must name a column -- a constant cannot supply this field. 상수는 전체 시트에 공통인 시간대나 통화 등에 사용합니다.

이러한 오류는 매핑 제안의 errors 목록 또는 해당 매핑을 사용한 업로드 처리 결과의 error_report에 나타납니다. 그러면 수집이 실패하며 준비된 데이터도 생성되지 않습니다.

daily_rates가 있다면 모든 요금이 객실 유형과 요금제에 속하므로 room_types와 rate_plans도 있어야 합니다. 시트에 요금제 열이 없다면 요금제 이름에 상수를 매핑하세요.

매핑은 .csv에만 적용됩니다. .json 파일과 함께 전송하면 수집에 실패합니다.

JSON 묶음

.json 파일은 아래 목록 중 일부 또는 전부를 담는 객체 하나입니다. 항목은 ref로 서로 참조합니다.

{
  "places": [
    {
      "ref": "harbor",
      "name": "Harbor Hotel",
      "timezone": "Europe/London",
      "lat": 51.5079,
      "lng": -0.0877,
      "address": "1 Example Street, London",
      "category": "hotel"
    }
  ],
  "room_types": [{ "ref": "double", "place_ref": "harbor", "name": "Double" }],
  "rate_plans": [{ "ref": "flex", "place_ref": "harbor", "name": "Flexible" }],
  "daily_rates": [
    {
      "place_ref": "harbor",
      "room_type_ref": "double",
      "rate_plan_ref": "flex",
      "stay_date": "2026-11-06",
      "price_amount": 189.0,
      "price_currency": "GBP"
    }
  ],
  "daily_inventory": [
    { "place_ref": "harbor", "room_type_ref": "double", "stay_date": "2026-11-06", "units_available": 4 }
  ],
  "hours": [
    { "place_ref": "harbor", "weekday": 0, "opens": "07:00", "closes": "23:00" },
    { "place_ref": "harbor", "valid_from": "2026-12-25", "valid_through": "2026-12-25", "is_closed": true }
  ],
  "documents": [
    { "title": "Cancellation policy", "text": "Free cancellation until 18:00 on the day before arrival." }
  ]
}

목록	필수 필드	참고
`places`	`name`, `timezone`, `lat`와 `lng` 또는 `address`	`ref`는 고유해야 하며 장소가 최소 하나 필요합니다.
`room_types`, `rate_plans`	`place_ref`, `name`	`ref`는 목록 내에서 고유해야 합니다.
`daily_rates`	`place_ref`, `room_type_ref`, `rate_plan_ref`, `stay_date`, `price_amount`, `price_currency`
`daily_inventory`	`place_ref`, `room_type_ref`, `stay_date`, `units_available`
`hours`	`place_ref`, `weekday` 또는 `valid_from` 날짜	`weekday`는 0~6이며 0은 월요일입니다. `opens`, `closes`는 시각입니다.
`documents`	`title`, `text`	인라인 텍스트만 허용

각 목록에는 크기 제한이 적용되는 선택적 필드도 있습니다. 필드 제한을 참조하세요.

문서 관련 사항:

문서는 title과 인라인 text로 구성됩니다. 문서에 넣은 저장 위치나 키는 무시되며, 외부 파일을 참조할 수 없습니다.
선택적 mime은 텍스트 형식을 설명합니다. text/plain, text/markdown, text/html은 그대로 유지하며 다른 값은 모두 text/plain으로 기록합니다.

숫자는 유한해야 합니다. NaN이나 Infinity는 좌표·가격·개수로 인정되지 않으며 자유 형식 JSON 필드에서도 허용되지 않습니다. 해당 행은 오류로 보고됩니다.

업로드 처리 흐름

업로드 한 번으로 ingest(처리 작업) 하나와 release(버전이 있는 결과물) 하나가 생성됩니다. 릴리스는 게시 전까지 draft입니다. 게시 작업은 기존에 게시된 릴리스를 한 번에 교체하므로 사용자가 부분적으로 적용된 데이터를 보지 않으며 교체 과정에서 조직의 데이터가 일시적으로 사라지는 일도 없습니다. 게시 릴리스를 없애려면 현재 버전을 게시 취소해야 합니다.

propose a mapping  ─►  stage a preview  ─►  check the result  ─►  publish
   (optional,            POST /ingests        GET /ingests/{id}     POST /ingests/{id}/publish
    for a sheet)         preview: true

later, to take a release back out:   unpublish  ─►  delete
                                      POST /releases/{id}/unpublish    DELETE /releases/{id}

1. 매핑 제안(선택 사항)

매핑되지 않은 시트가 있을 때 사용하세요. 내보낸 파일 전체가 아닌 헤더와 일부 데이터 행을 포함하는 파일의 앞부분만 전송합니다.


요청	`POST /inference-api/vendor/mapping/propose`
권한	업로드 권한을 가진 Enterprise 조직의 소유자 또는 관리자
본문	`{ "csv_head": "<the first characters of your file>" }`
제한	`csv_head`는 1~16,384자. 계정당 시간당 30개 제안
비용	각 제안은 조직의 AI 크레딧을 사용합니다. 제안에 사용된 토큰만큼 청구되며 이 페이지의 다른 호출은 크레딧을 쓰지 않습니다.

curl -X POST https://api.kaleidr.com/inference-api/vendor/mapping/propose \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"csv_head":"Property,Address,Room,Plan,Date,Nightly Rate,Available\nHarbor Hotel,\"1 Example Street, London\",Double,Flexible,2026-11-06,189.00,4\nHarbor Hotel,\"1 Example Street, London\",Suite,Flexible,2026-11-06,320.00,1\n"}'

{
  "mapping_spec": { "places": { "ref_from": ["Property"], "fields": { "name": "Property", "address": "Address", "timezone": { "const": "Europe/London" } } }, "room_types": { "ref_from": ["Room"], "fields": { "name": "Room" } } },
  "notes": "Time zone inferred from the addresses.",
  "columns": ["Property", "Address", "Room", "Plan", "Date", "Nightly Rate", "Available"],
  "sample_result": { "places": 1, "room_types": 2, "rate_plans": 1, "daily_rates": 2, "daily_inventory": 2 },
  "errors": []
}

응답 해석 방법:

sample_result를 확인하세요. 제안된 매핑을 샘플 행에 실행하고 섹션별 생성 항목 수를 보고합니다. 업로드 전에 매핑이 맞아 보이지만 아무것도 생성되지 않는 상황을 발견할 수 있습니다.
200 응답에서도 errors가 비어 있지 않을 수 있습니다. 적용할 수 없는 제안도 모든 문제와 함께 반환되므로 처음부터 다시 시작하지 않고 매핑을 수정할 수 있습니다. 필수 필드에 열이 없음, 존재하지 않는 열 이름, 잘못된 IANA 시간대, 세 글자가 아닌 통화 등이 포함됩니다.
완성된 행만 최대 다섯 개 샘플링합니다. csv_head가 줄 바꿈으로 끝나지 않으면 마지막 줄은 불완전한 행일 수 있으므로 제외합니다.
아무것도 저장하지 않습니다. 제안을 수정한 후 다음 단계에서 직접 전송해야 합니다. (sample_result)

상태	의미
403 `org_admin_required`	어느 조직에서도 소유자나 관리자가 아닙니다.
403 `vendor_data_not_on_plan`	소유자 또는 관리자지만 업로드 가능한 Enterprise 조직이 없습니다.
422	`csv_head`가 16,384자를 초과하거나, 헤더가 없거나, 열 이름이 중복되거나, 완성된 데이터 행이 없습니다. `detail`에 원인이 표시됩니다.
429, 요청 빈도 제한	지난 한 시간 동안 이 계정이 30개 넘게 제안했습니다.
429, AI 크레딧	이번 기간에 조직의 AI 크레딧을 모두 사용했습니다.
502 `mapping proposal unavailable`	제안을 생성하지 못했습니다. 다시 시도하거나 수동으로 매핑하세요.

두 가지 429 구별하기

두 거부 응답 모두 429 상태 코드입니다. 본문을 확인하세요.

	요청 빈도 제한	AI 크레딧 소진
본문	`{ "detail": "at most 30 mapping proposals per hour" }`	표준 할당량 응답 본문
구별 방법	`error` 필드가 없고 `detail`에 위 문장이 있습니다.	`"error": "quota_exceeded"` 및 `limit`, `used`, `remaining`, `reset_at`
해결 방법	계정당 지난 1시간을 기준으로 계산하므로 기다립니다.	`reset_at`까지 기다리거나 AI 크레딧을 추가하거나 매핑을 직접 작성합니다.

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "tier": "enterprise",
  "remaining": 0,
  "reset_at": "2026-11-01T04:00:00+00:00",
  "period": "month",
  "reset_in_seconds": 1296000
}

예시에는 실제 존재하는 네 필드가 생략되었습니다. limit, used는 조직 계약의 허용량과 사용량을 나타냅니다. product, meter는 업로드가 Studio 기능이므로 API가 아니라 Kaleidr Studio의 계량기를 가리킵니다. 크레딧 풀은 동일한 조직 AI 크레딧입니다. 다른 할당량 거부와 마찬가지로 error에 따라 분기하세요.

제안 비용 계산:

403, 422 또는 빈도 제한 429로 거부된 요청에는 크레딧이 들지 않습니다. 샘플 때문에 422로 거부된 요청도 시간당 30회 제한에 포함됩니다.
응답이 없어 제안이 생성되지 못한 경우(502)에도 비용이 들지 않습니다.
응답은 생성되었지만 사용할 수 없어 502가 반환된 경우에는 그 응답의 토큰이 청구됩니다.
errors가 비어 있지 않아도 생성된 제안은 일반 제안처럼 청구됩니다.

Studio에서는 각각 "매핑 제안 시간당 한도에 도달했습니다. 나중에 다시 시도하거나 매핑을 직접 수정하세요."와 "이번 기간의 조직 AI 크레딧이 모두 소진되었습니다. 매핑은 직접 작성할 수 있습니다."라고 안내합니다. 직접 작성한 매핑은 제안 호출이나 AI 크레딧이 필요하지 않습니다.

2. 미리보기 준비


요청	`POST /shared-api/datahub/ingests`
권한	Enterprise의 소유자 또는 관리자
헤더	`Idempotency-Key`, 길이 8~128자, 필수

본문 필드	유형	기본값	의미
`filename`	최대 200자의 문자열	필수	`.csv` 또는 `.json`으로 끝나야 하며 확장자로 파서를 선택합니다.
`artifact`	문자열	필수	원본 파일의 텍스트
`source`	`"csv"`, `"api"`, `"manual"`	`"csv"`	데이터 출처 표시용이며 파서를 선택하지 않습니다. `"json"`은 유효하지 않아 422를 반환합니다.
`mapping_spec`	최대 64 KB의 객체	없음	시트 열 매핑. 장소 CSV 또는 JSON 묶음에서는 생략합니다.
`preview`	불리언	`false`	`true`이면 게시 전에 확인하도록 준비만 하고 멈춥니다. `false`이면 읽는 즉시 게시합니다.
`org_id`	UUID	기본 조직	업로드 대상 조직

curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: places-2026-10-10-a" \
  -d '{
    "filename": "places.csv",
    "source": "csv",
    "preview": true,
    "artifact": "name,timezone,lat,lng,address,category\nHarbor Hotel,Europe/London,51.5079,-0.0877,\"1 Example Street, London\",hotel\n"
  }'

{
  "ingest_id": "5f0c2a1e-…",
  "release_id": "a81d77b0-…",
  "status": "pending",
  "status_url": "/shared-api/datahub/ingests/5f0c2a1e-…",
  "dispatched": true
}

**Idempotency-Key**는 조직 범위에서 유효합니다. 동일한 키로 재전송하면 두 번째 작업을 만들지 않고 기존 ingest를 dispatched: false와 함께 반환합니다. 매핑 변경 후 다시 준비하는 경우처럼 의도적으로 재처리한다면 새 키를 사용하세요. 기존 키를 쓰면 이전 매핑의 ingest가 반환됩니다.

**dispatched**는 이 호출에서 처리가 시작됐는지 나타냅니다. 새 ingest에서 false이면 시작되지 않아 pending 상태로 유지되므로 재실행 호출로 시작하세요.

최초 업로드 및 매핑 변경 시에는 preview: true를 사용하세요.

동시에 한 업로드만 처리하며 시간당 한도가 있습니다. 같은 조직에서 다른 업로드가 처리 중이거나 지난 한 시간에 30개 업로드를 시작했다면 새 요청이 거부됩니다.

상태	`detail`	의미	조치
409	`org_ingest_in_progress`	조직의 다른 ingest가 `running` 상태입니다.	그 작업이 `succeeded` 또는 `failed`가 될 때까지 조회하고 동일한 `Idempotency-Key`로 재전송합니다.
429	`ingest_rate_limited`	조직이 지난 한 시간에 ingest 30개를 만들었습니다. 미리보기도 포함됩니다.	기다렸다 다시 전송하세요. 반복 준비 대신 매핑 제안 호출을 사용해 매핑을 검사하세요.
413	`request_body_too_large`	전체 요청 크기가 32 MiB를 초과합니다.	파일을 줄이세요. 제한을 참조하세요.

이미 사용한 Idempotency-Key 를 다시 보내도 새 업로드로 간주되지 않습니다. 기존 수집 작업이 반환되며 위의 409 또는 429 제한으로 거부되지 않습니다. 요청 본문을 최초 요청과 비교하지 않으므로 사용한 키로 다른 파일을 보내도 그 파일은 무시됩니다. 다만 키를 조회하기 전에 요청을 먼저 검증하기 때문에 재요청이라도 413, 403 org_admin_required 또는 vendor_data_not_on_plan, 혹은 제한에 따른 422로 거부될 수 있습니다. 키는 관련 릴리스가 존재하는 동안 보관됩니다. 릴리스가 삭제되거나 자동 제거되면 같은 키로 새로운 업로드가 시작됩니다.

3. 결과 확인


요청	`GET /shared-api/datahub/ingests/{ingest_id}`
권한	모든 요금제의 소유자 또는 관리자

curl https://api.kaleidr.com/shared-api/datahub/ingests/5f0c2a1e-… \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

{
  "ingest_id": "5f0c2a1e-…",
  "release_id": "a81d77b0-…",
  "status": "succeeded",
  "attempts": 1,
  "row_counts": {
    "places": 1,
    "room_types": 0,
    "rate_plans": 0,
    "daily_rates": 0,
    "daily_inventory": 0,
    "hours": 0,
    "documents": 0
  },
  "error_report": null,
  "created_at": "2026-10-10T09:12:04Z",
  "started_at": "2026-10-10T09:12:20Z",
  "finished_at": "2026-10-10T09:12:41Z"
}

status는 pending에서 running으로, 마지막으로 succeeded 또는 failed로 변경됩니다.

**succeeded**일 때 row_counts는 데이터 종류별 인식된 항목 수입니다. 게시 전에 예상한 수와 비교하세요.
**failed**일 때 error_report.errors는 읽지 못한 행과 이유를 최대 200개까지 표시하며 총 오류 수는 error_report.error_count에 있습니다. 실패한 작업은 게시된 릴리스를 변경하지 않습니다.

{
  "status": "failed",
  "error_report": {
    "errors": [
      "places[1]: missing lat/lng -- supply coordinates, or an address to geocode from",
      "places[2]: unknown timezone 'London'"
    ],
    "error_count": 2
  }
}

업로드는 전체 성공 또는 전체 실패입니다. 행 하나라도 검증에 실패하면 해당 업로드에서 어떤 데이터도 준비되지 않습니다. 파일을 수정하고 새로운 Idempotency-Key로 다시 업로드하세요.

4. 게시


요청	`POST /shared-api/datahub/ingests/{ingest_id}/publish`
권한	Enterprise 소유자 또는 관리자
본문	없음

curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests/5f0c2a1e-…/publish \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

응답은 준비 요청 응답과 같은 구조이며 status: "pending"을 포함합니다. preview: true로 준비한 후 succeeded가 된 ingest만 게시할 수 있습니다.

게시할 때 파일을 다시 처리합니다. 동일한 파일과 매핑을 읽으므로 미리보기와 개수 및 식별자가 일치합니다. 단, 주소만 제공한 장소는 다시 지오코딩하므로 더 정확한 결과가 나오면 좌표가 약간 달라질 수 있습니다.

상태를 한 번 더 조회하세요. ingest가 pending으로 돌아갔다가 실행되고 succeeded로 종료됩니다. 이때 새 릴리스가 게시되고 기존 릴리스가 대체됩니다.

여기서 409는 실패가 아니라 "이미 진행 중"으로 취급하세요. 게시 호출에는 Idempotency-Key가 필요하지 않습니다. 클라이언트에서는 시간 초과가 났지만 Kaleidr에서는 성공했다면 재시도에 409 ingest_is_not_a_preview가 반환될 수 있습니다. 두 호출이 겹치면 409 publish_already_in_progress입니다. 두 경우 모두 게시가 진행되거나 이미 완료됐다는 뜻이므로 재호출하지 말고 ingest 상태를 확인하세요.

409 중에는 다른 경우가 있습니다. org_ingest_in_progress 는 조직의 다른 업로드가 처리 중이므로 이번 게시는 시작되지 않았음을 뜻합니다. 해당 수집 작업이 succeeded 또는 failed 상태가 될 때까지 기다린 후 게시를 다시 요청하세요.

한 단계로 게시하기

preview: false를 보내거나 preview를 생략하면 파일을 읽는 즉시 게시되며 별도 게시 호출이 없습니다. 매핑을 검증한 정기 업로드에 사용하세요.

멈춘 수집 작업 다시 시작하기


요청	`POST /shared-api/datahub/ingests/{ingest_id}/dispatch`
권한	Enterprise 소유자 또는 관리자

ingest가 pending에 머물거나(예: dispatched가 false) 데이터 자체의 문제가 아닌 이유로 failed가 됐다면 사용합니다. ingest 한 건은 최대 세 번 처리됩니다.

상태	의미
409 `ingest_already_succeeded`	이미 완료되어 할 일이 없습니다.
409 `ingest_already_running`	처리 중입니다.
409 `ingest_attempts_exhausted`	세 번의 시도를 모두 사용했습니다. 새 `Idempotency-Key`로 업로드하세요.
409 `org_ingest_in_progress`	조직의 다른 ingest가 처리 중입니다. 종료된 뒤 재호출하세요.
404 `ingest_not_found`	조직에 해당 ID의 수집 작업이 없거나, 관련 릴리스가 삭제 중이거나 이미 삭제되었습니다. 다시 시작할 작업이 없습니다.

릴리스 목록 조회


요청	`GET /shared-api/datahub/releases`
권한	모든 요금제의 소유자 또는 관리자
쿼리	선택적 `status`: `draft`, `published`, `superseded`, `failed`, `deleting`. 다른 값은 422 `unknown_release_status`를 반환합니다. `org_id`도 선택 사항입니다.

curl "https://api.kaleidr.com/shared-api/datahub/releases?status=published" \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

[
  {
    "id": "a81d77b0-…",
    "status": "published",
    "published_at": "2026-10-10T09:15:02Z",
    "superseded_at": null,
    "created_at": "2026-10-10T09:12:04Z",
    "state": "published",
    "ingest_id": "5f0c2a1e-…"
  }
]

필드	유형	의미
`id`	UUID	게시 취소와 삭제에 사용하는 릴리스 식별자
`status`	문자열	`draft`, `published`, `superseded`, `failed`, `deleting`
`published_at`	타임스탬프 또는 null	게시 시각
`superseded_at`	타임스탬프 또는 null	교체·게시 취소·미리보기 만료 등으로 현재 버전이 아니게 된 시각
`created_at`	타임스탬프	업로드 승인 시각
`state`	문자열	릴리스에 대해 지금 가능한 작업. 아래 표 참조
`ingest_id`	UUID 또는 null	릴리스를 만든 ingest 식별자. 상태와 게시 호출에 사용

state는 status를 기반으로 하되 초안 상태를 두 가지로 구분하므로 클라이언트는 추가 요청 없이 어떤 작업을 제공할지 알 수 있습니다.

`state`	`status`	의미	가능한 작업
`processing`	`draft`	업로드가 대기 중이거나 읽히는 중입니다. 한 단계 게시나 게시 진행 중인 미리보기도 포함됩니다.	기다리거나 삭제
`preview`	`draft`	준비가 완료되어 사용자의 결정을 기다리는 미리보기	게시 또는 삭제
`published`	`published`	답변에 사용되는 릴리스	게시 취소
`superseded`	`superseded`	최신 릴리스로 교체되었거나 게시 취소 또는 미리보기 만료됨	삭제
`failed`	`failed`	업로드를 읽지 못함	삭제
`deleting`	`deleting`	삭제 진행 중	없음

목록은 최신 릴리스 50개를 최신순으로 보여줍니다. 조직당 동시에 published 릴리스는 최대 하나이며 게시 취소 후에는 없습니다. 삭제 중인 릴리스는 ?status=deleting으로 요청하지 않는 한 목록에서 제외되고, 삭제가 완료되면 모든 목록에서 사라집니다.

릴리스 서비스 중단 및 제거

데이터 제거에는 의도적으로 분리된 두 API가 있습니다. 게시 취소는 게시 릴리스를 서비스에서 내리고, 삭제는 게시되지 않은 릴리스를 제거합니다. 두 API 모두 모든 요금제의 소유자 또는 관리자가 사용할 수 있어 업로드할 수 없는 요금제로 변경한 조직도 데이터를 철회할 수 있습니다. 본문이나 Idempotency-Key가 필요 없고 반복 호출도 안전합니다.

Kaleidr Studio에서

Data for AI Answers 섹션의 Releases 목록은 각 행에 적합한 작업을 표시하고 전송 전에 확인을 요청합니다. Enterprise를 해지한 조직이라도 릴리스가 남아 있는 동안 소유자와 관리자는 이 목록과 두 작업에 접근할 수 있으며, 업로드 단계 대신 "업로드는 Enterprise 요금제의 기능입니다." 문구가 나타납니다.

행 표시	작업	확인 문구	이후 표시
Published	Unpublish	"이 릴리스의 게시를 취소하시겠습니까? 다른 릴리스를 게시할 때까지 Kaleidr AI는 이 데이터로 답변하지 않으며 이 릴리스를 다시 게시할 수 없습니다."	"게시 취소 중…" 이후 "게시가 취소되었습니다. Kaleidr AI가 이 데이터를 사용해 답변하지 않습니다." 행이 Superseded로 변경됩니다.
Draft, Superseded, Failed	Delete	"이 릴리스와 여기서 생성된 모든 데이터를 영구적으로 삭제하시겠습니까? 취소할 수 없습니다."	"삭제 중…" 이후 "릴리스가 삭제되었습니다." 행이 사라집니다.
Processing	없음

각 확인 창에는 실행 버튼과 Cancel 버튼이 있습니다. 게시 릴리스에 Delete가 표시되지는 않으며 해당 API 오류는 "이 릴리스는 게시 중입니다. 삭제하기 전에 게시를 취소하세요."로 표시됩니다. 자세한 내용은 Releases 목록을 참조하세요.

릴리스 게시 취소


요청	`POST /shared-api/datahub/releases/{release_id}/unpublish`
권한	모든 요금제의 소유자 또는 관리자
본문	없음
쿼리	선택적 `org_id`

curl -X POST https://api.kaleidr.com/shared-api/datahub/releases/a81d77b0-…/unpublish \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

{ "release_id": "a81d77b0-…", "status": "superseded" }

호출이 반환되는 즉시 릴리스는 서비스에서 제외됩니다. 그 결과는 다음과 같습니다.

다른 릴리스를 게시할 때까지 조직에는 게시 릴리스가 없습니다. 이전에 사용하던 릴리스도 자동 복구되지 않습니다. 답변은 일반 지식을 계속 사용하며, 데이터가 사라졌다는 안내는 표시되지 않습니다.
같은 릴리스를 다시 게시할 수 없습니다. 같은 데이터를 복구하려면 파일을 다시 업로드하고 게시해야 합니다.
릴리스는 superseded로 목록에 남아 삭제할 수 있으며 수동으로 삭제하지 않아도 자동 제거됩니다.

상태	`detail`	의미
200		릴리스가 `superseded`입니다. 반복해도 동일한 200이 반환됩니다. 새 버전으로 이미 대체된 릴리스도 같습니다. `superseded`
403	`org_admin_required`	조직 소유자 또는 관리자가 아닙니다.
404	`release_not_found`	조직에 해당 릴리스가 없거나 삭제 중입니다.
409	`release_not_published`	초안이거나 실패한 릴리스로 게시된 적이 없어 취소할 것이 없습니다.

릴리스 삭제


요청	`DELETE /shared-api/datahub/releases/{release_id}`
권한	모든 요금제의 소유자 또는 관리자
본문	없음
쿼리	선택적 `org_id`

curl -X DELETE https://api.kaleidr.com/shared-api/datahub/releases/a81d77b0-… \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

HTTP/1.1 202 Accepted

{ "release_id": "a81d77b0-…", "status": "deleting", "dispatched": true }

삭제하면 릴리스, 해당 릴리스의 업로드 파일 및 Kaleidr가 생성한 모든 산출물이 영구 제거되며 되돌릴 수 없습니다.

게시 릴리스는 먼저 게시를 취소해야 합니다. 게시 중인 릴리스의 삭제는 409 release_is_published를 반환합니다. 그 외의 미리보기·대체됨·실패·읽기 진행 중 릴리스는 삭제할 수 있습니다.
응답은 202이며 실제 삭제는 곧 완료됩니다. 응답한 순간부터 릴리스는 deleting이 되고 목록에서 제외되며 게시할 수 없고, 해당 ingest 조회는 404 ingest_not_found를 반환합니다. 이는 상태 조회와 재실행 요청에도 적용됩니다.
**dispatched**는 이 호출이 삭제를 시작했는지 나타냅니다. false여도 조금 뒤 자동 실행되며 다시 호출할 수도 있습니다.
반복 호출은 안전합니다. 진행 중에는 같은 202가 반환되고 완료된 뒤에는 404 release_not_found가 반환됩니다. 이 404는 "이미 삭제됨"으로 취급하세요.

상태	`detail`	의미
202		릴리스가 `deleting` 상태이며 완료 전 반복해도 동일합니다.
403	`org_admin_required`	조직 소유자 또는 관리자가 아닙니다.
404	`release_not_found`	조직에 릴리스가 없으며 삭제가 완료된 경우도 포함됩니다.
409	`release_is_published`	릴리스가 게시되어 있습니다. 게시 취소 후 삭제하세요.

삭제 완료를 확인하려면 ?status=deleting으로 릴리스 목록을 조회하세요. 목록이 비어 있으면 진행 중인 삭제가 없습니다.

오래된 릴리스 자동 제거

더 이상 현재 버전이 아닌 릴리스는 직접 삭제하지 않아도 됩니다. Kaleidr가 삭제 API와 동일한 방식으로 제거합니다.

릴리스	제거 시점
`superseded`: 새 릴리스로 교체되거나 게시 취소됨	교체 또는 취소 후 30일
게시하지 않은 미리보기	14일 후 만료되고 추가 30일 후 삭제
`failed`	마지막 처리 시도 종료 후 30일
`published`	게시 중에는 제거되지 않음

삭제되지 않는 데이터

삭제 완료 후 새로 생성하는 답변에는 삭제 릴리스가 사용되지 않습니다. 다만 삭제는 일정 기간 유지되는 캐시 답변, 저장된 채팅 기록, 백업 또는 데이터 처리 중 모델 제공자에게 이미 전달된 텍스트에는 적용되지 않습니다. 자세한 내용은 삭제 범위 밖의 항목을 참조하세요.

제한

계약으로 정해지는 제한

업로드 크기와 개수 제한은 조직 계약에 명시됩니다. 플랫폼은 각 제한에 기술적 상한을 적용하며 조직 계약으로도 이 상한을 초과할 수 없습니다.

제한	Enterprise	초과 시
`artifact` 크기	계약에서 지정	업로드 시 422
헤더를 제외한 CSV 행 수	계약에서 지정	업로드 시 422
JSON 묶음의 장소 수	계약에서 지정	업로드 시 422
JSON 묶음의 문서 수	계약에서 지정	업로드 시 422

GET /shared-api/datahub/limits로 조직에 적용되는 제한을 조회할 수 있습니다.
Free 및 Pro에서는 업로드 자체가 불가능하므로 업로드 한도가 없습니다. 호출 시 403 vendor_data_not_on_plan을 반환합니다.
제한은 조직 단위입니다. 게시 시 이전 릴리스 전체를 교체하므로 업로드 한 번과 게시 데이터 모두에 해당 제한이 적용됩니다.

제한을 넘긴 업로드는 422를 반환하며 각 오류 사유에는 제한과 요금제가 표시됩니다. 전송한 수는 <count>, 조직의 한도는 <limit>로 표현됩니다.

{ "detail": { "errors": ["<count> places exceed the limit of <limit> (enterprise plan)"] } }

나머지 세 오류 메시지는 다음 형식입니다. <count> documents exceed the limit of <limit> (enterprise plan), csv has more than <limit> rows; the places limit is <limit> (enterprise plan), artifact is <size> MB; the limit is <limit> MB (enterprise plan). 파일이 크기 한도를 넘으면 추가로 읽지 않기 때문에 그 사유 하나만 반환합니다.

모든 조직에 적용되는 고정 제한

제한	값	초과 시
업로드 요청 전체 크기	32 MiB	413 `request_body_too_large`
업로드 한 번의 객실 유형 수	10,000	JSON에서는 업로드 시 422, 매핑 시트에서는 ingest 실패
업로드 한 번의 요금제 수	10,000	JSON에서는 업로드 시 422, 매핑 시트에서는 ingest 실패
JSON 묶음의 영업시간 행 수	25,000	업로드 시 422
업로드당 숙박일별 요금과 가용 객실 행의 총합	200,000	수집 실패: `daily facts: <count> rows exceed the cap of 200000`
업로드당 모든 문서의 텍스트 총량	최대 약 600,000자, 여러 문서로 나뉘면 더 적음	수집 실패: `documents: chunk count exceeds the cap of 500`
JSON 중첩 깊이	과도한 중첩 거부	업로드 시 422
`mapping_spec`	64 KB	업로드 시 422
`filename`	200자, `.csv` 또는 `.json` 확장자	업로드 시 422
조직당 동시 처리 업로드	1	409 `org_ingest_in_progress` (업로드, 게시 및 재실행 시)
조직당 새 업로드	시간당 30개	429 `ingest_rate_limited`
제안용 `csv_head`	16,384자	422
매핑 제안	계정당 시간당 30개, 제안마다 AI 크레딧 사용	429: 두 429 구별하기
ingest당 처리 시도	3회	재실행 시 409
게시하지 않은 미리보기	14일	게시 시 409
더 이상 현재 버전이 아닌 릴리스	30일	자동 제거

파일은 JSON 요청 안의 문자열로 전달되며 이스케이프로 더 길어질 수 있으므로 요청 전체 제한이 파일 크기 한도보다 큽니다. 32 MiB 초과 요청은 내용을 읽기 전에 413으로 거부됩니다. 요청 자체는 한도 안에 있지만 조직의 파일 크기 한도를 넘은 경우 422가 반환됩니다.

크기나 개수가 한도를 넘으면 사유를 최대 200개 포함한 422가 반환됩니다. 모든 조직에 공통인 행 수 제한 초과 메시지는 다음과 같은 형태입니다.

{ "detail": { "errors": ["10001 room_types exceed the cap of 10000"] } }

JSON 중첩이 너무 깊어 읽을 수 없는 경우에도 같은 형식의 응답을 반환합니다.

{ "detail": { "errors": ["upload is nested too deeply"] } }

CSV 한도는 행의 의미와 관계없이 모든 행을 계산합니다. 밤마다 한 행이 있는 숙박 요금표는 한도에 금방 도달하므로 대규모 요금·재고 데이터는 JSON 묶음으로 전송하세요. JSON에서는 장소, 문서, 객실 유형, 요금제 및 영업시간 행 수가 업로드 시 계산됩니다.

필드 제한

모든 값에는 최대 크기가 있습니다. 텍스트는 문자 수로 측정하고, 객체나 배열 같은 자유 형식 JSON 값은 JSON으로 직렬화한 뒤 바이트 수로 측정합니다.

목록	필드	한도
모든 목록	`ref`, `place_ref`, `room_type_ref`, `rate_plan_ref`	128자
`places`	`name`	200자
`places`	`category`	100자
`places`	`timezone`	64자
`places`	`overture_id`(선택 사항)	128자
`places`	`address`	JSON으로 2,048바이트
`places`	`schema_org`(선택적 객체)	JSON으로 16,384바이트
`room_types`	`name`	200자
`room_types`	`amenities`(선택적 배열), `attributes`(선택적 객체)	각각 JSON으로 8,192바이트
`rate_plans`	`name`	200자
`rate_plans`	`currency`(선택 사항)	3자
`rate_plans`	`cancellation_policy`(선택 사항)	2,000자
`rate_plans`	`board_basis`(선택 사항)	100자
`rate_plans`	`attributes`(선택적 객체)	JSON으로 8,192바이트
`hours`	`note`(선택 사항)	500자
`documents`	`title`	300자

한도 초과를 보고하는 위치는 전송 형식에 따라 달라집니다.

JSON 묶음은 업로드 시 검사하며 422와 함께 행 및 필드를 명시합니다. 예: places[3]: name is longer than 200 characters 또는 room_types[0]: amenities is larger than 8192 bytes as JSON.
장소 CSV나 매핑된 시트는 ingest 처리 중 검사되므로 failed로 종료되며 동일한 사유가 error_report.errors에 기록됩니다.

자유 형식 JSON 값에 NaN 또는 Infinity가 들어 있으면 <list>[<row>]: <field> holds a non-finite number 오류를 보고합니다.

미리보기 만료

게시하지 않은 미리보기는 준비 완료 14일 후 폐기됩니다. superseded로 표시되어 잠시 릴리스 목록에는 남아 있지만 게시할 수는 없습니다. 게시 요청에는 409 no_previewed_release_to_publish가 반환됩니다. 계속하려면 다시 업로드하세요. 다른 대체 릴리스와 마찬가지로 추가 30일 후 자동 제거되며 그 전에 삭제할 수도 있습니다.

필드 관련 참고 사항

모든 장소에는 timezone이 필요하며 답변 내용에도 영향을 줍니다. 요금과 재고는 장소 자체의 현지 날짜로 해석합니다. 시드니 호텔의 "오늘 밤"은 런던의 "오늘 밤"과 날짜가 다를 수 있습니다. 내보내기 데이터에 시간대 열이 없다면 상수로 매핑하세요.

{ "timezone": { "const": "Australia/Sydney" } }

시간대를 신중히 선택하세요. 잘못 설정하면 낮에는 대부분 맞지만 자정 부근에는 틀린 답변이 나옵니다. 시간대가 없거나 유효한 IANA 명칭이 아니면 오류로 보고됩니다.

좌표가 있으면 제공하세요. lat, lng는 제공한 값 그대로 사용됩니다. 주소만 제공했다면 지오코딩하며 신뢰도가 낮은 일치는 추측하지 않고 해당 행을 오류로 보고해 좌표를 제공하도록 합니다. 해결되지 않은 장소를 보고하는 편이 잘못된 곳에 핀을 찍는 것보다 낫습니다.

동일한 내보내기 파일을 다시 업로드해도 안전합니다. 매핑된 시트의 식별자는 ref_from으로 지정한 열에서 파생되므로 같은 파일은 같은 식별자를 만듭니다. 새 릴리스는 이전 릴리스를 대체할 뿐 누적 추가하지 않습니다.

각 릴리스는 자체로 완전해야 합니다. 이전 릴리스에서 유지되는 정보는 없습니다. 새 파일에서 지난달 장소를 누락하면 게시 후 그 장소는 답변에서 사라집니다.

텍스트는 UTF-8로 전송하세요. ZIP, gzip 또는 PDF를 .csv나 .json으로 이름만 바꿔도 거부됩니다.

오류

업로드 API 오류는 사유 목록을 반환하는 경우를 제외하고 { "detail": "<code>" } 구조를 사용합니다.

상태	`detail`	의미
401		액세스 토큰이 없거나 만료됐거나 올바른 액세스 토큰이 아닙니다.
403	`org_admin_required`	조직 소유자나 관리자가 아닙니다.
403	`vendor_data_not_on_plan`	조직이 Enterprise가 아닙니다. 업로드·게시·재실행에서 반환되며 조회·게시 취소·삭제는 요금제로 거부되지 않습니다.
404	`ingest_not_found`	조직에 해당 ingest가 없거나 릴리스가 삭제 중 또는 삭제 완료됐습니다.
404	`release_not_found`	조직에 해당 릴리스가 없습니다. 삭제 완료 릴리스를 포함해 게시 취소·삭제 호출에서 반환됩니다.
409	`release_not_published`	초안 또는 실패 릴리스에 게시 취소를 요청했습니다.
409	`release_is_published`	게시 릴리스 삭제를 요청했습니다. 게시를 먼저 취소하세요.
409	`ingest_conflict`	동일한 `Idempotency-Key`를 사용하는 두 업로드가 충돌했습니다. 다시 요청하세요.
409	`ingest_is_not_a_preview`	미리보기로 준비되지 않았거나 이미 게시를 요청했습니다.
409	`ingest_already_running`	ingest가 처리 중입니다.
409	`no_previewed_release_to_publish`	미리보기가 실패했거나 완료되지 않았거나 만료되었습니다.
409	`publish_already_in_progress`	게시 호출 두 개가 겹쳤으며 하나가 처리 중입니다.
409	`ingest_already_succeeded`	완료된 ingest에 재실행을 요청했습니다.
409	`ingest_attempts_exhausted`	세 번의 처리 시도 이후 재실행했습니다.
409	`org_ingest_in_progress`	조직의 다른 ingest가 처리 중입니다. 종료 후 다시 요청하세요.
413	`request_body_too_large`	업로드 요청이 32 MiB 초과입니다. 게시·재실행·조회 호출은 1 MiB로 제한됩니다.
422	`{ "errors": [ … ] }`	파일이나 매핑의 한도 초과, 필드의 크기 제한 초과, 과도한 JSON 중첩 또는 CSV/JSON 읽기 실패입니다. 사유는 문장으로 표시되며 요금제 한도 초과 시 한도와 요금제가 명시됩니다.
429	`ingest_rate_limited`	조직이 지난 한 시간에 30개 업로드를 시작했습니다.
422	검증 오류 목록	`Idempotency-Key` 누락, 다른 확장자, `source`의 잘못된 값 등 필드 누락·형식 오류
422	`unknown_release_status`	`status` 필터가 허용된 다섯 값 중 하나가 아닙니다.

파일 자체가 조직 크기 한도를 초과하면 errors에 이유가 포함된 422를 반환합니다. 요청 전체의 크기를 넘으면 413과 { "detail": "request_body_too_large" }를 반환합니다.

매핑 제안 호출의 오류는 매핑 제안에 별도로 설명되어 있습니다. 업로드 권한이 없는 계정은 403 org_admin_required 또는 vendor_data_not_on_plan, 시간당 제안 한도나 조직 AI 크레딧을 소진한 경우에는 429를 반환합니다.

현재 제공되지 않는 기능

증분 업데이트: upsert, 개별 레코드 삭제 또는 "변경 내용 조회" 호출은 없습니다. 새 릴리스는 이전 버전 전체를 대체하며 릴리스는 전체 단위로 게시 취소 또는 삭제할 수 있습니다.
이전 릴리스 재게시: 대체되거나 게시 취소된 릴리스는 다시 현재 버전으로 만들 수 없습니다. 파일을 다시 업로드해야 합니다.
매핑 저장: 매핑은 업로드마다 전송해야 하며 ID로 저장·참조할 수 없습니다.
커넥터: Kaleidr는 데이터베이스, 예약 시스템, 스프레드시트 서비스에서 데이터를 직접 가져오지 않습니다.
멀티파트 또는 이진 파일 업로드: 파일은 JSON 본문 내부의 문자열로 전송됩니다.

이 기능의 위치​

이용 가능 조건​

조직의 업로드 가능 범위​

인증​

업로드할 수 있는 데이터​

장소 CSV​

열 매핑이 있는 시트​

JSON 묶음​

업로드 처리 흐름​

1. 매핑 제안(선택 사항)​

두 가지 429 구별하기​

2. 미리보기 준비​

3. 결과 확인​

4. 게시​

한 단계로 게시하기​

멈춘 수집 작업 다시 시작하기​

릴리스 목록 조회​

릴리스 서비스 중단 및 제거​

Kaleidr Studio에서​

릴리스 게시 취소​

릴리스 삭제​

오래된 릴리스 자동 제거​

삭제되지 않는 데이터​

제한​

계약으로 정해지는 제한​

모든 조직에 적용되는 고정 제한​

필드 제한​

미리보기 만료​

필드 관련 참고 사항​

오류​

현재 제공되지 않는 기능​

관련 문서​