Upload API

Upload은 파일을 올려 만드는 임시 리소스입니다. Media를 만들기 전 첫 단계로, 파일을 올리면 응답으로 Upload 하나가 돌아오고, 이 Upload의 정보를 가지고 Media를 생성합니다. Media 생성은 CMA(Weegloo User) 또는 ACMA(Service User)에서 이루어지며 이 페이지의 범위 밖입니다.

Upload은 임시 리소스입니다. 생성 후 24시간이 지나면 만료되고(expiresAt), 그 안에 Media로 만들지 않으면 사라집니다. Upload에는 발행이나 버전 개념이 없습니다(version·status·publish 속성이 없습니다). 본문 필드도 없으며 시스템 속성 sys만 가집니다. 베이스 URL은 https://upload.weegloo.com/v1이고, 모든 요청에 Upload를 인증하는 Bearer 토큰이 필요합니다.

리소스 구조

다음은 옷가게 상품 사진(텀블러 이미지)을 한 Space에 올린 Upload의 응답입니다. sys만 있고, 그 안에 owner·expiresAt·size 같은 키가 들어 있습니다.

{
  "sys": {
    "id": "4bgMfu7cFGYDRQn4jdqFI8tkOWKZIm",
    "type": "Upload",
    "owner": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T04:48:44.057Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T04:48:44.057Z",
    "expiresAt": "2026-06-19T04:48:44.057Z",
    "size": 50847
  }
}

주요 키:

• sys.id: Upload의 고유 식별자입니다. Media를 만들 때 이 값을 넘깁니다. 단일 조회·삭제 경로의 {uploadId}에도 들어갑니다.
• sys.owner: 이 Upload가 속한 곳을 가리키는 참조입니다. targetType이 Space 또는 Organization입니다(아래 Space와 Organization 컨텍스트 참조).
• sys.expiresAt: 만료 시각입니다. createdAt 기준 24시간 뒤이며, 이 시각이 지나면 Upload가 사라집니다.
• sys.size: 올린 파일의 크기입니다(바이트). 위 예시는 50847바이트입니다.

시스템 속성 (sys)

모든 Upload은 시스템 속성을 sys 객체에 담습니다. owner·createdBy·updatedBy는 Refer 모양({ "sys": { "id", "type": "Refer", "targetType" } })으로 들어갑니다.

위 9개 속성은 모두 응답에 항상 포함됩니다. Content나 Content Type의 sys에 있는 version·status·publish는 Upload에 없습니다. Upload은 발행하거나 버전을 매기는 리소스가 아니라, Media를 만들기 위한 일회용 재료이기 때문입니다. owner는 다른 리소스의 space처럼 한 종류만 가리키지 않고, targetType에 따라 Space 또는 Organization을 가리킵니다.

Space와 Organization 컨텍스트

Upload은 두 가지 컨텍스트에서 만들 수 있고, 컨텍스트에 따라 경로와 sys.owner가 달라집니다.

Space 컨텍스트의 Upload은 그 Space의 Media를 만드는 재료입니다. Organization 컨텍스트의 Upload은 조직 아이콘처럼 조직에 직접 쓰이는 파일을 올릴 때 사용합니다. 두 경우 모두 응답으로 돌아오는 리소스 구조는 같고, sys.owner의 targetType 값만 다릅니다.

올리는 방식: multipart과 binary

파일을 올리는 POST 요청에는 두 가지 방식이 있습니다. 어느 쪽이든 응답으로 돌아오는 것은 같은 Upload 리소스입니다.

multipart 방식은 요청 본문을 multipart/form-data로 보냅니다. 파일은 이름이 file인 폼 필드에 담습니다. 브라우저의 파일 선택 입력에서 바로 올리는 경우처럼, 폼 데이터로 보내는 상황에 적합합니다.

binary 방식은 파일의 원시 바이트를 요청 본문에 그대로 담습니다. 본문의 미디어 타입(Content-Type)에 제약이 없으며(보통 application/octet-stream을 씁니다), Space 컨텍스트에서는 Content-Length 헤더에 본문의 바이트 길이를 함께 보내야 합니다. 폼 구조 없이 파일 바이트만 전송하는 서버 측 코드 등에 적합합니다.

API

아래 모든 엔드포인트의 기준 URL은 https://upload.weegloo.com/v1이며, Authorization 헤더에 Upload를 인증하는 Bearer 토큰이 필요합니다. 먼저 Space 컨텍스트의 4개, 이어 Organization 컨텍스트의 4개를 다룹니다.

관련 문서

• Media: 올린 Upload로 Media를 만드는 요청 형식.
• Media (개념): 파일 자산을 콘텐츠 스튜디오에서 다루는 법.