빠른 시작

이 가이드를 완료하면 Onttle에 콘텐츠를 등록하고 REST API로 조회하는 전체 흐름을 경험할 수 있습니다. 약 10분이 소요됩니다.

사전 조건: Onttle 계정이 필요합니다. 없다면 회원가입을 먼저 완료하세요.

1단계: Workspace 생성

Workspace는 멤버, 결제, 사용량을 관리하는 최상위 단위입니다.

대시보드에 로그인합니다.
하단의 새 Workspace 만들기를 클릭합니다.
Workspace 이름을 입력하고 생성을 클릭합니다.

2단계: Project 생성

Project는 API Key와 테이블 데이터를 분리하는 애플리케이션 단위입니다.

Workspace 홈에서 새 Project 버튼을 클릭합니다.
Project 이름(예: my-blog)을 입력합니다.
초대할 멤버와 언어를 선택합니다.
오른쪽 영역에서 AI를 이용해 프로젝트의 테이블 구조를 생성할 수 있습니다. 직접 만들려면 '직접 만들기'를 선택합니다.
프로젝트 만들기를 클릭합니다.

3단계: 테이블 (Table) 생성 및 컬럼 (Column) 추가

테이블은 콘텐츠 스키마를 정의하는 단위입니다. 테이블 생성과 컬럼 추가는 하나의 테이블 생성 화면에서 함께 진행됩니다. 이 예제에서는 블로그 게시물 테이블을 만듭니다.

프로젝트 → 테이블 메뉴에서 테이블 추가 버튼을 클릭합니다.
테이블 이름을 posts로 입력합니다.
컬럼 추가 버튼을 클릭하고 아래 컬럼을 순서대로 추가합니다.

컬럼 이름	타입	옵션
`title`	TEXT	required
`body`	EDITOR	—
`published_date`	DATE	—

만들기를 클릭합니다.

4단계: 첫 콘텐츠 작성

프로젝트 → 테이블 → posts 테이블을 클릭합니다.
콘텐츠 추가 버튼을 클릭합니다.
title, body, published_at 필드를 채웁니다.
우측 하단에서 상태를 초안으로 저장 혹은 저장 후 발행으로 저장합니다.

콘텐츠 상태가 Published여야 외부 API에서 기본적으로 조회됩니다.

5단계: API Key 발급

Project 설정의 API Keys 메뉴를 클릭합니다.
새 API Key 버튼을 클릭합니다.
이름을 입력하고 허용된 호스트에 도메인을 입력합니다.
생성을 클릭하고 발급된 키를 복사합니다.

API Key는 생성 직후에만 전체 값이 표시됩니다. 반드시 안전한 곳에 저장하세요.

6단계: 환경 변수 설정

발급한 API Key를 환경 변수로 관리합니다. 코드에 직접 입력하지 마세요.

# .env.local
ONTTLE_API_KEY=your_api_key_here

7단계: Contents 조회

이제 REST API로 콘텐츠를 조회합니다. {projectId}는 Project 설정에서 확인할 수 있습니다.

curl

curl https://api.onttle.com/v1/{projectId}/tables/posts/contents \
  -H "Authorization: Bearer $ONTTLE_API_KEY"

TypeScript (fetch)

const res = await fetch(
  'https://api.onttle.com/v1/{projectId}/tables/posts/contents?status=PUBLISHED',
  {
    headers: {
      Authorization: `Bearer ${process.env.ONTTLE_API_KEY}`,
    },
  },
)

const { list, pagination } = await res.json()

성공 응답 예시

{
  "list": [
    {
      "id": "cnt_01hxk2",
      "slug": "hello-onttle",
      "status": "PUBLISHED",
      "data": {
        "title": "Hello Onttle",
        "published_at": "2026-08-30T09:00:00.000Z"
      },
      "created_at": "2026-08-30T09:00:00.000Z",
      "updated_at": "2026-08-30T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

문제 해결

증상	확인 사항
`401 Unauthorized`	Authorization 헤더 포함 여부와 API Key 값 확인
`403 Forbidden`	API Key의 권한(읽기/쓰기) 및 Project 범위 확인
`list`가 빈 배열	콘텐츠 상태가 `PUBLISHED`인지 확인
`404`	`{projectId}`와 테이블 이름(`posts`) 확인

다음 단계

개념 설명 — Workspace, Project, Table의 관계를 더 깊이 이해합니다.
테이블 설계 — 더 복잡한 스키마를 설계하는 방법을 알아봅니다.
인증 방식 — API Key 권한과 보안 관리 방법을 확인합니다.