모든 겹 앱을
API로 연결하세요

API & AI에서 노트 조회와 노트 작성·수정 권한의 키를 만든 뒤 환경 변수에 보관합니다.

export GYEOP_API="/server/v1"
export GYEOP_TOKEN="layer_pat_..."

curl -X POST "$GYEOP_API/notes" \
  -H "Authorization: Bearer $GYEOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "AI가 작성한 회의록",
    "client_request_id": "meeting-20260730-001",
    "content_markdown": "# 회의 요약\n\n- 결정 사항\n- 다음 작업",
    "visibility": "private"
  }'

실제 API에서 생성한 341개 작업입니다. 기능 목록 JSON과 OpenAPI에서 요청·응답 형식을 확인할 수 있습니다.

드로우·캔버스·프레젠테이션·갤러리는 노트 블록의 Tiptap JSON으로 읽고 수정합니다. 이 블록의 속성은 Markdown으로 변환하지 않고 유지하세요. 기본 노트 API의 id는 공개 식별자이고, 앱 기능 API의 숫자 page_id는 노트 조회 응답에서 얻습니다.

문서 전체 교체가 필요하지 않다면 먼저 블록 목록을 읽고 blockId를 기준으로 삽입·교체·이동·삭제하세요. 노트 본문 수정은 expected_version으로 사람의 최신 변경을 보호합니다.

curl -X POST "$GYEOP_API/notes/NOTE_PUBLIC_ID/blocks" \
  -H "Authorization: Bearer $GYEOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_version": 3,
    "position": "after",
    "anchor_block_id": "BLOCK_ID",
    "block": {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [{ "type": "text", "text": "결정 사항" }]
    }
  }'

자율 에이전트에는 drafts:write만 주어 변경 제안을 만들게 하고, 별도의 승인 클라이언트에 drafts:approve와 notes:write를 부여할 수 있습니다. 제안은 원본 버전이 바뀌면 적용되지 않습니다.

• • POST /batch는 최대 50개 노트를 먼저 검증하며 dry_run: true로 결과를 미리 볼 수 있습니다.
• • GET /changes는 30일간의 변경을 증가하는 cursor로 읽습니다. 처리한 cursor를 저장하면 중복 처리에도 안전합니다.
• • Webhook은 공개 HTTPS 443 주소만 허용하고, 생성 시 한 번 표시되는 비밀키로 X-Layer-Signature-256을 검증합니다. 연속 실패하면 자동 비활성화됩니다.
• • MCP는 tools/list에서 키가 실제로 가진 권한의 도구만 노출하며, 최신 2026-07-28과 2025-11-25 클라이언트를 지원합니다.

{
  "mcpServers": {
    "gyeop": {
      "url": "/server/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${GYEOP_TOKEN}"
      }
    }
  }
}

멤버 관리에는 workspaces:manage, 공개 범위와 둘러보기·SEO·댓글 관리에는 publications:manage를 별도로 부여합니다. API 키를 가진 사용자에게도 겹의 기존 소유자·권한 관리자 역할 제한이 그대로 적용됩니다.

curl -X POST "$GYEOP_API/workspaces" \
  -H "Authorization: Bearer $GYEOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI 프로젝트",
    "icon": "✨"
  }'

curl -X POST "$GYEOP_API/workspaces/WORKSPACE_ID/members" \
  -H "Authorization: Bearer $GYEOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "login": "sUser1",
    "role": "editor"
  }'

curl -X PATCH "$GYEOP_API/notes/NOTE_PUBLIC_ID/publication" \
  -H "Authorization: Bearer $GYEOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "public",
    "expected_version": 3,
    "explore_enabled": true,
    "seo_index_enabled": true,
    "public_comments_enabled": true
  }'

• • 역할은 viewer, editor, manager이며 manager는 자신보다 높은 역할을 관리할 수 없습니다.
• • 공개 범위는 private, unlisted, public입니다. 둘러보기·검색 노출·공개 댓글은 public에서만 켤 수 있습니다.
• • 노트 생성·수정 요청에서 visibility를 바꾸려면 notes:write와 publications:manage가 모두 필요합니다.

대부분의 AI에는 content_markdown이 가장 간단합니다. 제목 H1~H4, 문단, 굵게·기울임·취소선·인라인 코드·링크, 인용, 글머리·번호·할 일 목록, 구분선과 코드 블록을 변환합니다. 고급 겹 블록은 전체 Tiptap content JSON을 사용합니다.

curl -X PATCH "$GYEOP_API/notes/NOTE_PUBLIC_ID" \
  -H "Authorization: Bearer $GYEOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content_markdown": "## 후속 내용\n\n새로운 진행 상황입니다.",
    "content_mode": "append",
    "expected_version": 3
  }'

content_mode: "append"는 기존 본문 뒤에 추가하고, 기본값 replace는 본문 전체를 교체합니다.

• • POST에는 작업마다 고유한 client_request_id를 보내세요. 같은 본문과 ID를 24시간 안에 재시도해도 노트가 중복 생성되지 않습니다.
• • GET 응답의 version을 PATCH의 expected_version으로 보내세요.
• • 누군가 먼저 저장했다면 409 Conflict가 반환됩니다. 최신 노트를 다시 읽고 변경을 병합하세요.
• • 기본 요청 제한은 키당 1분 120회이며 초과 시 429와 Retry-After가 반환됩니다.
• • 목록은 최대 100개이며 next_offset이 있으면 다음 페이지를 요청합니다.
• • 문서 본문 요청 크기는 최대 1MB입니다.

아래 텍스트 문서 주소와 원하는 작업을 AI에게 전달하세요. API 키는 AI 제품이 제공하는 Secret·환경 변수 입력란에 별도로 저장합니다.