Markhub API

우리 서버에서 HTTPS 요청 한 번으로 Markhub 허브에 메시지·노트·할 일을 올립니다. 알림, 모니터링, 야간 리포트처럼 스크립트가 팀 앞에 꺼내 놓아야 하는 것에 씁니다.

이 페이지 목차

빠르게 시작하기
인증
메시지 올리기
노트 만들기
할 일 만들기
코드 예시
오류와 한도
팀에게 보이는 모습

빠르게 시작하기

Markhub 에서 워크스페이스 메뉴를 열고 설정 → API 로 갑니다.
키 발급 을 누르고, 키가 글을 올릴 허브와 필요한 권한(scope)을 고릅니다.
키를 복사합니다. mk_live_ 로 시작하고 한 번만 보여주니 바로 서버 비밀값으로 저장하세요.
첫 메시지를 보냅니다.

curl

curl -X POST https://makigql.shop/api/public/v1/messages \
  -H "Authorization: Bearer $MARKHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"**Deploy finished**: api v2.14.0 is live."}'

메시지는 워크스페이스의 MAKi 봇 이름으로 허브에 바로 올라옵니다.

인증

모든 엔드포인트는 https://makigql.shop/api/public/v1 아래에 있습니다. 요청마다 키를 Bearer 토큰으로 보냅니다.

헤더

Authorization: Bearer mk_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

키는 서버의 환경변수나 비밀값 저장소에 둡니다. 브라우저나 모바일 앱에 절대 넣지 마세요.
키 하나는 허브 하나에만 올립니다. 여러 허브에 올리려면 허브마다 키를 발급하세요.
권한은 키가 만들 수 있는 것을 정합니다. 메시지 생성, 노트 생성, 할 일 생성. 권한 밖의 엔드포인트를 부르면 403 입니다.
재발급 은 새 키를 만들고 옛 키를 24시간 더 살려 두어 중단 없이 바꿀 수 있습니다. 폐기 는 키를 즉시 막습니다.

메시지 올리기

POST /api/public/v1/messages · 권한 메시지 생성

필드	타입	설명
`text`	string	마크다운(굵게, 목록, 링크, 코드). `blocks` 를 안 보내면 필수.
`blocks`	array	Markhub 에디터 블록. 이미 블록을 만드는 쪽에서 씁니다. 둘 다 오면 `blocks` 를 씁니다.

요청 본문

{ "text": "**payment-worker** crashed on prod (exit 137). Restarting." }

응답 · 201 Created

{
  "success": true,
  "data": {
    "id": "5a85019d-…",
    "conversationId": "2c0683cf-…",
    "createdAt": "2026-09-11T12:24:05.092Z"
  }
}

노트 만들기

POST /api/public/v1/notes · 권한 노트 생성

필드	타입	설명
`content`	string	필수. 노트 본문(마크다운).
`title`	string	선택.

요청 본문

{
  "title": "Nightly report 2026-09-11",
  "content": "## Orders\n- 1,240 shipped\n- 17 late (1.4%)"
}

응답 · 201 Created

{
  "success": true,
  "data": { "id": "…", "bucketId": "…", "createdAt": "…" }
}

할 일 만들기

POST /api/public/v1/todos · 권한 할 일 생성

필드	타입	설명
`title`	string	필수.
`content`	string	선택. 세부 내용(마크다운).
`dueDate`	string	선택. ISO 8601, 예: `2026-09-12T09:00:00Z`.
`priority`	string	선택. `LOW`, `MEDIUM`, `HIGH`, `URGENT` 중 하나.

요청 본문

{
  "title": "Investigate 5xx spike on /checkout",
  "content": "Started 02:14 UTC.",
  "dueDate": "2026-09-12T09:00:00Z",
  "priority": "HIGH"
}

응답 · 201 Created

{
  "success": true,
  "data": { "id": "…", "bucketId": "…", "createdAt": "…" }
}

코드 예시

Node.js 18+

await fetch("https://makigql.shop/api/public/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MARKHUB_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Nightly sync done. 1,240 orders imported." }),
});

Python

import os, requests

requests.post(
    "https://makigql.shop/api/public/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['MARKHUB_API_KEY']}"},
    json={"text": "Nightly sync done. 1,240 orders imported."},
    timeout=10,
)

오류와 한도

상태	뜻
`201`	만들어짐. 본문에 새 `id` 가 있습니다.
`400`	본문이 잘못됨. 예: 메시지에 `text` 도 `blocks` 도 없음, `dueDate` 가 날짜가 아님.
`401`	키가 없거나 틀렸거나 만료·폐기됨.
`403`	키에 이 엔드포인트 권한이 없거나 호출 한도를 넘음.
`404`	키가 올리던 허브가 삭제됨.

키 하나당 1분에 60회 까지 부를 수 있습니다. 넘으면 5분 동안 막히고, 요청은 Retry-After(초) 헤더와 함께 403 을 받습니다.

오류는 JSON 으로 옵니다. 분기는 statusCode 로 하고, message 는 로그용 설명으로만 보세요.

오류 본문

{
  "statusCode": 403,
  "message": "…",
  "timestamp": "2026-09-11T12:24:31.033Z",
  "path": "/api/public/v1/messages"
}

재시도한 요청은 한 번 더 올라갑니다. 타임아웃에 재시도한다면 실행 ID 같은 표식을 본문에 넣어 중복을 쉽게 알아보게 하세요.

팀에게 보이는 모습

글은 워크스페이스의 MAKi 봇 이름으로 올라오고, 허브와 스트림에서 허브 멤버 모두에게 실시간으로 보입니다.
팀원은 다른 메시지처럼 답장하거나, 반응하거나, 할 일·노트로 바꿀 수 있습니다.
어느 키로 올렸는지 기록돼서 연동을 서로 구분할 수 있습니다.

궁금한 점이나 여기서 다루지 않는 쓰임새가 있으면 admin@markhub.ink 으로 메일 주세요.