API

파일 목록 조회

작성일 2026.03.18 | 수정일 2026.03.18

GET/storage/v1/files

Query

fileId— 파일 ID로 필터링(32자)

type— 파일 타입으로 필터링

originalName— 파일명으로 필터링

name— 원본 파일명으로 필터링

url— URL로 필터링

handleKey— 참조 핸들 키로 필터링

category— 참조 카테고리로 필터링

refId— 참조 ID로 필터링(32자)

startKey— 페이지네이션 시작 키

limit— 반환할 레코드 수(최소 1, 최대 1000, 기본값 20)

dateCreated— 수정일시 필터(ISO 8601). 지원 연산자 gte, lte

dateUpdated— 수정일시 필터(ISO 8601). 지원 연산자 gte, lte

lightbulb

지원 연산자를 사용하실 경우 Query Operator 가이드를 참조하세요.

파일 타입 필터링 사용시 스토리지 공통 파일 타입을 참조하세요.

Response

Name	Type	Required	Description
fileList	array	*	파일 목록
fileId	string	*	파일 고유 ID (32자)
accountId	string	*	계정 고유 ID
name	string	*	파일명
originalName	string		원본 파일명
url	string	*	파일 접근 URL
type	string	*	파일 타입
link	string\|null		파일 연결 URL
width	number		이미지 가로 크기 (px)
height	number		이미지 세로 크기 (px)
fileSize	number	*	파일 크기 (bytes)
references	array	*	파일 참조 목록
dateCreated	string	*	생성일시 (ISO 8601)
dateUpdated	string	*	수정일시 (ISO 8601)
startKey	string\|null	*	현재 페이지 시작 키
nextKey	string\|null	*	다음 페이지 시작 키. null이면 마지막 페이지

Structure

Response

{
  "fileList": [
    {
      "fileId": "ST01FZ_abc12345678901234567890",
      "accountId": "12345678901234",
      "name": "프로모션 배너",
      "originalName": "NyT7u.jpg",
      "url": "https://coolsms-storage.s3.ap-northeast-2.amazonaws.com/12345678901234/ST01FZ_abc12345678901234567890",
      "type": "KAKAO",
      "link": "https://example.com/promotion",
      "width": 800,
      "height": 400,
      "fileSize": 102400,
      "references": [],
      "dateCreated": "2024-07-01T12:00:00.000Z",
      "dateUpdated": "2024-07-01T12:00:00.000Z"
    }
  ],
  "startKey": null,
  "nextKey": "ST01FZ_def12345678901234567890"
}