REST API

Kanorio 관리 REST API를 사용하면 백엔드 프로그램에서 HTTPS를 통해 직접 사이트를 읽고 쓸 수 있습니다. 사이트 생성 및 설정, 페이지 섹션 및 블로그 게시물 읽기/쓰기, 컬렉션 및 디지털 제품 관리, 미디어 라이브러리 이미지 업로드, 주문 및 연락처 조회, 사이트 게시 및 사용자 지정 도메인 관리 등이 가능합니다.

기본적인 기능은 AI 어시스턴트(MCP) 연결과 동일하지만, 호출 방식에 차이가 있습니다.

• AI 어시스턴트(MCP) 연결: ChatGPT, Claude, Cursor와 같은 AI가 대화 맥락에 따라 자율적으로 운영합니다.
• 관리 REST API(본 가이드): 예약된 스크립트, 사용자 지정 백엔드, CI/CD 파이프라인 또는 자동화 노드에서 명시적인 코드를 사용하여 특정 엔드포인트를 호출합니다.
• 콘텐츠 전달 API 및 고객 API: 사이트 자체 도메인에서 호스팅되는 공개 읽기 및 멤버 로그인용 API입니다(콘텐츠 전달 API 및 사용자 지정 프론트엔드에서 멤버 로그인 및 디지털 전달 통합 참조).

기본 URL: https://app.kanorio.com/api/v1

전체 엔드포인트, 매개변수 및 오류 코드(SSOT): 모든 엔드포인트 경로, 쿼리 매개변수, 요청/응답 예시, 속도 제한 및 오류 코드 표는 공개된 관리 API 참조 페이지의 코드 계약에서 실시간으로 생성됩니다(기계 판독 가능 사양: https://app.kanorio.com/api/v1/openapi.json). 본 가이드는 인증, 동시성 안전성 및 지원 중단 정책에 중점을 둡니다.

인증 및 권한 규칙

REST API는 knr_pat_로 시작하는 만 허용합니다. 모든 요청에 Authorization 헤더를 포함하십시오.

Authorization: Bearer knr_pat_your_key

• 키 생성 방법: "계정 설정 › API 액세스"로 이동하여 "키 생성"을 클릭하고, "기타 도구"를 선택한 다음 활성화하려는 사이트와 권한 범위를 체크하십시오.
• 실제 권한 계산: $\text{실제 권한} = \text{키 권한} \cap \text{사이트 내 멤버 역할}$
• OAuth 토큰은 허용되지 않음: ChatGPT나 Claude를 통해 "허용"을 클릭하여 얻은 연결 토큰은 /api/mcp로 제한되며 REST API를 호출하는 데 사용할 수 없습니다.

보안 경고: knr_pat_ 키는 귀하의 개인 관리 ID와 동일합니다. 항상 서버 측 환경 변수나 비밀 관리 서비스에 저장하십시오. 브라우저 측 프론트엔드 코드, 모바일 앱 또는 공개 Git 저장소에 키를 하드코딩하지 마십시오.

핵심 쓰기 메커니즘: 초안 경계 및 낙관적 잠금

1. 사이트 ID(:id)를 가져오는 방법

모든 사이트 수준 엔드포인트 경로는 /sites/:id/...로 시작합니다. "사이트 설정 › 일반"으로 이동하여 맨 아래로 스크롤하면 websiteId를 복사할 수 있으며, GET /api/v1/sites를 호출하여 키로 액세스할 수 있는 모든 사이트를 나열할 수도 있습니다.

2. 초안 vs 즉시 게시

• 초안으로 작성됨(라이브 사이트를 업데이트하려면 POST /sites/:id/publish 필요): 페이지 섹션(PUT .../sections), 머리글 및 바닥글(PUT .../globals/header|footer), 사이트 전체 버튼 및 소셜 링크, 사이트 모양 설정. 블로그 게시물 추가 및 수정도 작업 복사본만 업데이트하므로, 공개하려면 POST .../posts/:postId/publish를 호출해야 합니다.
• 기본적으로 즉시 게시됨: 컬렉션 항목(items.*는 기본적으로 publish: true; 초안으로 저장하려면 publish: false 전달), 스토어 제품, 디지털 제품.

3. 덮어쓰기 방지 메커니즘(낙관적 잠금 ifUnmodifiedSince)

팀원(또는 다른 AI 어시스턴트)이 대시보드 편집기를 사용하여 변경한 내용을 스크립트가 덮어쓰지 않도록, 페이지 섹션 및 사이트 전체 탐색을 작성할 때 낙관적 동시성 제어를 사용합니다.

• 페이지 섹션 업데이트(PUT /sites/:id/pages/:pageId/sections): 먼저 페이지를 읽어 updatedAt 타임스탬프를 가져오고 요청에 ifUnmodifiedSince: "<updatedAt>"을 포함해야 합니다.
• 머리글, 바닥글 및 사이트 설정 업데이트: 먼저 GET /sites/:id/globals를 호출하여 contentUpdatedAt 타임스탬프를 가져오고 요청에 ifUnmodifiedSince: "<contentUpdatedAt>"을 포함해야 합니다.
• 마지막으로 읽은 후 다른 사람이 리소스를 수정한 경우, 서버는 쓰기를 거부하고 409 CONFLICT(최신 타임스탬프 포함)를 반환합니다. 다시 읽고, 병합하고, 다시 제출하십시오.

빠른 시작: 읽기부터 게시까지 4단계 요청

키를 환경 변수로 설정합니다:

export KANORIO_TOKEN="knr_pat_your_key"

1. 사이트 목록을 나열하고 사이트 ID 가져오기

curl -s https://app.kanorio.com/api/v1/sites \
  -H "Authorization: Bearer $KANORIO_TOKEN"

2. 페이지 목록을 읽어 홈페이지 id 및 updatedAt 가져오기

curl -s https://app.kanorio.com/api/v1/sites/ws_example123/pages \
  -H "Authorization: Bearer $KANORIO_TOKEN"

3. ifUnmodifiedSince를 사용하여 페이지 섹션 초안 업데이트

curl -s -X PUT https://app.kanorio.com/api/v1/sites/ws_example123/pages/pg_example456/sections \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ifUnmodifiedSince": "2026-10-15T08:00:00.000Z",
    "sections": [
      {
        "id": "sec_hero_1",
        "type": "page-main-visual",
        "title": "Artisan Bakery",
        "description": "Handcrafted sourdough bread and French pastries, baked fresh every morning."
      }
    ]
  }'

4. 사이트 게시

curl -s -X POST https://app.kanorio.com/api/v1/sites/ws_example123/publish \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

속도 제한 및 지원 중단 정책

• 속도 제한: 키별로 독립적으로 계산됩니다. 일반 엔드포인트는 분당 120회 요청, 게시/게시 취소 엔드포인트는 시간당 30회 요청입니다. 이를 초과하면 Retry-After 헤더와 함께 429 RATE_LIMITED가 반환됩니다.
• 버전 및 변경 로그: 모든 추가 및 변경 사항은 공개 API 변경 로그에 기록됩니다.
• 지원 중단 기간: 엔드포인트를 제거하거나 주요 변경 사항을 적용해야 하는 경우, 안정 버전(Stable version)에 대해 최소 6개월의 지원 중단 기간을 준수합니다. 응답에는 표준 Deprecation, Sunset, Link 헤더가 자동으로 포함되며, 최근 30일 이내에 해당 엔드포인트를 호출한 키 소유자에게 사전에 알림을 보냅니다.

관련 문서