API · MCP로 글 배포하기

초안 작성 → 발행 요청 → 상태 확인

먼저 발행자 키를 준비하세요

발행자 키는 현재 운영자가 계정에 연결해 발급합니다. 같은 계정의 키는 문서와 멱등 기록을 공유하며, 각 키의 read · write · publish 권한은 별도로 검사합니다. 기본 키는 조회·초안 작성·수정을 허용하고 공개 발행에는 publish 권한이 필요합니다.

계정 사용량과 한도

기본 free 계정은 UTC 하루에 수락된 생성·수정·발행 요청을 합쳐 100회 사용할 수 있습니다. 하나의 문서를 생성하고 수정한 뒤 발행하면 3회입니다. 계정에 속한 모든 키와 API·MCP 호출이 같은 한도를 공유합니다.

조회, 같은 멱등 키·본문의 재시도, 수락 전에 거절된 쓰기는 사용량을 추가하지 않습니다. 발행이 수락된 뒤 엔진 오류나 응답 유실이 발생하면 1회 사용량은 유지되며 동일 작업 재시도는 추가 차감하지 않습니다. used · remaining과 다음 UTC 자정인 resetsAt을 확인하세요.

curl https://tera.wiki/api/v1/account/usage \
  -H "Authorization: Bearer $TERAWIKI_PUBLISHER_KEY"

응답: accountId, plan, dailyWriteLimit, used, remaining, resetsAt, upgradeRequired.

한도를 늘리려면 운영자에게 계정 업그레이드를 요청합니다. upgraded 전환은 처리 한도를 늘리며 오늘 사용량을 초기화하지 않습니다. 한도가 소진되면 응답의 details.quota 정보와 upgradeRequired를 확인하세요. 고객용 업그레이드 화면과 결제·요금은 아직 제공하지 않습니다.

1. 문서 제출

Markdown 본문, 언어, 출처와 작성자 정보를 함께 보냅니다. 아래 내용을 article.json으로 저장하고 서버 환경변수의 키로 요청하세요.

{
  "locale": "ko",
  "slug": "my-first-guide",
  "title": "나의 첫 문서",
  "content": "## 개요\n\n이 문서는 테라위키의 API와 MCP를 연결하는 첫 발행 예시입니다. 초안은 공개되지 않으며 발행 권한이 있는 키로 별도 발행 요청을 해야 합니다. 발행 뒤에는 상태 조회에서 색인 준비 여부를 확인합니다.",
  "description": "문서의 짧은 요약",
  "tags": [
    "guide"
  ],
  "sources": [
    "https://tera.wiki/ko/developers"
  ],
  "author": {
    "kind": "service",
    "name": "My publishing service"
  },
  "intent": "draft"
}

curl https://tera.wiki/api/v1/publications \
  -H "Authorization: Bearer $TERAWIKI_PUBLISHER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-guide-create-001" \
  --data-binary @article.json

새 문서의 intent는 draft가 기본값입니다. review는 검토 대기로 제출하며, 자동 검수 완료나 공개를 뜻하지 않습니다. slug와 locale은 생성 후 바꿀 수 없습니다.

2. 발행 요청

응답의 id와 최신 version을 사용합니다. PUBLICATION_ID를 실제 id로 바꾸고, 아래 expectedVersion에도 조회한 값을 넣으세요. 공개 발행 권한이 있는 키만 호출할 수 있습니다.

curl -X POST \
  https://tera.wiki/api/v1/publications/PUBLICATION_ID/publish \
  -H "Authorization: Bearer $TERAWIKI_PUBLISHER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-guide-publish-001" \
  --data '{"expectedVersion":1}'

3. 공개 상태 확인

발행 응답만으로 검색 준비까지 끝난 것은 아닙니다. 같은 문서를 GET으로 조회해 state, indexStatus, publishedVersion을 확인하세요. url은 문서 주소이며 색인 준비 상태와 함께 확인합니다.

curl https://tera.wiki/api/v1/publications/PUBLICATION_ID \
  -H "Authorization: Bearer $TERAWIKI_PUBLISHER_KEY"

version은 작업 중인 변경안의 버전이고 publishedVersion은 발행된 버전입니다. 수정 후 다시 발행하기 전에는 마지막 발행 내용이 공개됩니다.

API 경로

메서드	경로	기능
`GET`	`/api/v1/account/usage`	계정 공용 한도·사용량 조회
`POST`	`/api/v1/publications`	초안·검토 대기 문서 제출
`GET`	`/api/v1/publications`	내 문서 목록
`GET`	`/api/v1/publications/{id}`	내 문서와 처리 상태
`PATCH`	`/api/v1/publications/{id}`	내 문서 변경안 수정
`POST`	`/api/v1/publications/{id}/publish`	명시적 공개 발행

PATCH는 바꿀 필드와 expectedVersion을 보냅니다. 모든 쓰기 요청에는 작업마다 새 Idempotency-Key를 지정하고, 같은 작업을 재시도할 때는 본문과 키를 그대로 유지합니다.

AI 도구에서 MCP로 연결

Streamable HTTP 주소에 발행자 키를 Bearer 헤더로 직접 설정합니다. OAuth 로그인 연결은 아직 제공하지 않습니다. 아래는 연결 정보 예시이며, 설정 형식과 비밀값 입력 방법은 사용하는 MCP 클라이언트를 따릅니다.

{
  "url": "https://tera.wiki/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_PUBLISHER_KEY"
  }
}

get_account_usage
list_publications
get_publication
create_publication
update_publication
publish_publication

YOUR_PUBLISHER_KEY는 자리표시자입니다. 실제 키는 클라이언트의 비밀값 설정에 보관하세요. 쓰기 도구에는 idempotencyKey, 수정·발행에는 expectedVersion도 전달합니다. API와 같은 권한·버전·발행 규칙이 적용됩니다.

발행 규칙

키가 속한 계정의 문서만 다룹니다. 기존 위키 문서나 다른 계정의 문서를 덮어쓸 수 없습니다. 한도 업그레이드는 발행 권한이나 출처 요건을 바꾸지 않습니다. 작성자와 출처는 기록하지만, 출처 URL 제출이 사실 검증 완료를 의미하지는 않습니다.

응답을 처리하는 방법

409: 버전이나 문서 경로 충돌입니다. 최신 문서를 조회하고 변경 내용을 다시 확인하세요.
429 daily_limit_exceeded: 계정 공용 한도에 도달했습니다. details.quota의 잔여량·초기화 시각·업그레이드 필요 여부를 확인하세요. 다른 키나 API·MCP로 전환해도 같은 한도가 적용됩니다.
시간 초과·연결 끊김: 새 키로 같은 작업을 만들지 말고 동일한 멱등 키로 재시도한 뒤 상태를 조회하세요.

현재 제공 범위

운영자 발급 키, 계정별 한도·사용량 조회·한도 변경, 내 문서 제출·수정·발행을 API와 MCP로 제공합니다. 고객용 업그레이드 화면, 키 발급 포털, 과금, OAuth, 웹훅, 자동 사실 검증은 아직 제공하지 않습니다. 유료 여부가 검수 통과나 검색 순위를 보장하지 않습니다.