데이터모델 API

데이터모델과 행(Row) 데이터를 조회하고 조작하는 API입니다.

기본 URL

https://suits.work/api/v1

모든 요청에는 인증 헤더가 필요합니다:

Authorization: Bearer sk_live_xxxxxxxxxxxx
Content-Type: application/json

참고: API 키에 워크스페이스 정보가 포함되어 있으므로, 별도의 workspaceId 파라미터는 필요하지 않습니다.

데이터모델

데이터모델 목록 조회

워크스페이스의 모든 데이터모델을 조회합니다.

GET /api/v1/datamodels

쿼리 파라미터

파라미터	타입	필수	설명	기본값
search	string	아니오	검색어 (title, id에서 검색)	-
limit	number	아니오	반환할 최대 개수	100
includeDetails	boolean	아니오	속성(properties) 포함	false
includeRowCounts	boolean	아니오	행 개수 포함	false

요청 예시

curl -X GET "https://suits.work/api/v1/datamodels" \
  -H "Authorization: Bearer YOUR_API_KEY"

응답

{
  "data": [
    {
      "id": "dm_abc123",
      "title": "고객",
      "icon": { "type": "emoji", "name": "👤" },
      "description": "고객 정보 관리",
      "createdAt": "2024-01-15T09:00:00Z",
      "updatedAt": "2024-03-20T14:30:00Z"
    },
    {
      "id": "dm_def456",
      "title": "영업기회",
      "icon": { "type": "emoji", "name": "💰" },
      "description": "영업 파이프라인",
      "createdAt": "2024-01-15T09:05:00Z",
      "updatedAt": "2024-03-21T10:15:00Z"
    }
  ],
  "meta": {
    "total": 2
  }
}

데이터모델 상세 조회

특정 데이터모델의 구조를 조회합니다.

GET /api/v1/datamodels/:dataModelId

응답

{
  "data": {
    "id": "dm_abc123",
    "title": "고객",
    "icon": { "type": "emoji", "name": "👤" },
    "description": "고객 정보 관리",
    "properties": [
      {
        "id": "prop_001",
        "name": "회사명",
        "type": "TEXT",
        "order": 1,
        "visible": true
      },
      {
        "id": "prop_002",
        "name": "이메일",
        "type": "TEXT",
        "order": 2,
        "visible": true
      },
      {
        "id": "prop_003",
        "name": "계약금액",
        "type": "CURRENCY",
        "order": 3,
        "visible": true
      },
      {
        "id": "prop_004",
        "name": "상태",
        "type": "SELECT",
        "options": [
          { "value": "lead", "label": "리드", "color": "gray" },
          { "value": "active", "label": "활성", "color": "green" },
          { "value": "churned", "label": "이탈", "color": "red" }
        ],
        "order": 4,
        "visible": true
      },
      {
        "id": "prop_005",
        "name": "담당자",
        "type": "RELATION",
        "relationConfig": {
          "targetDataModelId": "dm_members",
          "relationshipType": "MANY_TO_ONE"
        },
        "order": 5,
        "visible": true
      }
    ],
    "createdAt": "2024-01-15T09:00:00Z",
    "updatedAt": "2024-03-20T14:30:00Z"
  }
}

행 (Rows)

행 목록 조회

데이터모델의 행 데이터를 조회합니다.

GET /api/v1/datamodels/:dataModelId/rows

쿼리 파라미터

파라미터	타입	필수	설명	기본값
limit	number	아니오	반환할 최대 행 수	100
offset	number	아니오	페이지네이션 오프셋	0

요청 예시

curl -X GET "https://suits.work/api/v1/datamodels/dm_abc123/rows?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

응답

{
  "data": [
    {
      "id": "row_111",
      "data": {
        "prop_001": "테크스타트",
        "prop_002": "[email protected]",
        "prop_003": 50000000,
        "prop_004": "active",
        "prop_005": ["member_001"]
      },
      "createdAt": "2024-03-01T10:00:00Z",
      "updatedAt": "2024-03-15T14:30:00Z"
    },
    {
      "id": "row_112",
      "data": {
        "prop_001": "그로스랩",
        "prop_002": "[email protected]",
        "prop_003": 30000000,
        "prop_004": "lead",
        "prop_005": ["member_002"]
      },
      "createdAt": "2024-03-02T11:30:00Z",
      "updatedAt": "2024-03-02T11:30:00Z"
    }
  ],
  "meta": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

> **참고**: 응답의 `data` 필드 키는 속성의 `id` (prop_xxx)입니다. 속성 이름이 아닌 ID를 사용하므로, 먼저 데이터모델 상세 조회로 속성 ID와 이름 매핑을 확인하세요.

행 생성

새로운 행을 생성합니다. 단건 또는 배치 생성이 가능합니다.

POST /api/v1/datamodels/:dataModelId/rows

요청 바디 (단건)

{
  "data": {
    "prop_001": "뉴컴퍼니",
    "prop_002": "[email protected]",
    "prop_003": 25000000,
    "prop_004": "lead"
  }
}

요청 바디 (배치)

{
  "rows": [
    {
      "prop_001": "기업A",
      "prop_002": "[email protected]",
      "prop_004": "lead"
    },
    {
      "prop_001": "기업B",
      "prop_002": "[email protected]",
      "prop_004": "lead"
    }
  ]
}

응답 (단건)

{
  "data": {
    "id": "row_113",
    "data": {
      "prop_001": "뉴컴퍼니",
      "prop_002": "[email protected]",
      "prop_003": 25000000,
      "prop_004": "lead"
    },
    "createdAt": "2024-03-22T09:00:00Z"
  }
}

응답 (배치)

{
  "data": {
    "created": 2,
    "rows": [
      { "id": "row_114" },
      { "id": "row_115" }
    ]
  }
}

행 수정

기존 행의 데이터를 수정합니다. 변경할 속성만 포함합니다.

PATCH /api/v1/datamodels/:dataModelId/rows/:rowId

요청 바디

{
  "data": {
    "prop_004": "active",
    "prop_003": 35000000
  }
}

응답

{
  "data": {
    "id": "row_113",
    "data": {
      "prop_001": "뉴컴퍼니",
      "prop_002": "[email protected]",
      "prop_003": 35000000,
      "prop_004": "active"
    },
    "updatedAt": "2024-03-22T10:30:00Z"
  }
}

행 삭제

행을 삭제합니다.

DELETE /api/v1/datamodels/:dataModelId/rows/:rowId

응답

{
  "data": {
    "id": "row_113",
    "deleted": true
  }
}

필터링 (향후 지원 예정)

filter 파라미터로 조건에 맞는 행만 조회합니다.

기본 필터

// 단일 조건
const filter = {
  "상태": { "equals": "active" }
};

// URL 인코딩
const url = `/v1/datamodels/dm_abc/rows?filter=${encodeURIComponent(JSON.stringify(filter))}`;

지원되는 연산자

연산자	설명	지원 타입	예시
`equals`	정확히 일치	모든 타입	`{"상태": {"equals": "active"}}`
`not_equals`	일치하지 않음	모든 타입	`{"상태": {"not_equals": "churned"}}`
`contains`	포함	TEXT	`{"회사명": {"contains": "테크"}}`
`starts_with`	~로 시작	TEXT	`{"이름": {"starts_with": "김"}}`
`ends_with`	~로 끝남	TEXT	`{"이메일": {"ends_with": "@gmail.com"}}`
`greater_than`	초과	NUMBER, DATE	`{"금액": {"greater_than": 1000000}}`
`greater_than_or_equal`	이상	NUMBER, DATE	`{"금액": {"gte": 1000000}}`
`less_than`	미만	NUMBER, DATE	`{"금액": {"less_than": 5000000}}`
`less_than_or_equal`	이하	NUMBER, DATE	`{"금액": {"lte": 5000000}}`
`is_empty`	비어있음	모든 타입	`{"메모": {"is_empty": true}}`
`is_not_empty`	비어있지 않음	모든 타입	`{"이메일": {"is_not_empty": true}}`

복합 조건

AND 조건

{
  "and": [
    { "상태": { "equals": "active" } },
    { "계약금액": { "greater_than": 10000000 } }
  ]
}

OR 조건

{
  "or": [
    { "상태": { "equals": "active" } },
    { "상태": { "equals": "lead" } }
  ]
}

중첩 조건

{
  "and": [
    { "상태": { "equals": "active" } },
    {
      "or": [
        { "계약금액": { "greater_than": 50000000 } },
        { "등급": { "equals": "VIP" } }
      ]
    }
  ]
}

정렬

sort 파라미터로 결과를 정렬합니다.

sort=<속성명>:<방향>

예시

sort=createdAt:desc          # 최신순
sort=회사명:asc              # 가나다순
sort=계약금액:desc           # 금액 높은순

페이지네이션

대량의 데이터는 페이지네이션으로 나눠서 조회합니다.

커서 기반 페이지네이션

// 첫 번째 페이지
const response1 = await fetch('/v1/datamodels/dm_abc/rows?limit=20');
const data1 = await response1.json();

// 다음 페이지 (hasMore가 true인 경우)
if (data1.pagination.hasMore) {
  const response2 = await fetch(
    `/v1/datamodels/dm_abc/rows?limit=20&cursor=${data1.pagination.nextCursor}`
  );
}

속성별 값 형식

TEXT (텍스트)

{ "회사명": "슈츠" }
{ "이메일": "[email protected]" }
{ "URL": "https://suits.work" }

NUMBER (숫자)

{ "금액": 50000000 }
{ "수량": 100 }
{ "비율": 0.85 }

DATE (날짜)

ISO 8601 형식을 사용합니다.

{ "계약일": "2024-03-15" }
{ "마감일시": "2024-03-31T18:00:00Z" }

SELECT (선택)

옵션 값(value)을 사용합니다.

{ "상태": "active" }

MULTI_SELECT (다중 선택)

배열로 전달합니다.

{ "태그": ["VIP", "기업고객", "장기계약"] }

CHECKBOX (체크박스)

{ "완료여부": true }
{ "중요": false }

RELATION (관계)

관계된 행의 ID 배열을 사용합니다.

{ "담당자": ["member_001", "member_002"] }
{ "고객사": ["company_abc"] }

FILE (파일)

파일 업로드 후 반환된 URL을 사용합니다.

{ 
  "첨부파일": [
    { "url": "https://...", "name": "계약서.pdf" }
  ] 
}

에러 응답

공통 에러 형식

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "상세 에러 메시지",
    "details": {}
  }
}

주요 에러 코드

코드	HTTP	설명
`unauthorized`	401	인증 실패
`forbidden`	403	권한 없음
`not_found`	404	리소스 없음
`validation_error`	400	요청 데이터 오류
`rate_limited`	429	요청 제한 초과
`internal_error`	500	서버 오류

다음 단계

인증 - API 키 발급 및 관리
웹훅 - 실시간 이벤트 수신

On this page