API 레퍼런스

출시 예정 — 공개 REST API는 현재 로드맵에 포함되어 있으며 아직 사용할 수 없습니다. 아래 문서는 계획된 API 설계를 설명합니다. 제공 시작 시 체인지로그에서 공지됩니다.

PostClaw REST API를 사용하면 게시물, 플랫폼, 자동화, AI 생성을 프로그래밍 방식으로 관리할 수 있습니다.

기본 URL: https://app.postclaw.fun/v1

인증

모든 요청에는 Bearer 토큰이 필요합니다. 설정 → API 키에서 API 키를 생성하세요.

curl https://app.postclaw.fun/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY"

키의 범위는 read, write, admin으로 구분됩니다. 필요한 최소 범위를 사용하세요.

속도 제한

모든 응답에는 속도 제한 헤더가 포함됩니다:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1743484800

엔드포인트

게시물

# 게시물 목록 조회
GET /v1/posts?status=scheduled&limit=20

# 게시물 생성
POST /v1/posts
{
  "content": "캡션 내용",
  "platforms": ["twitter", "linkedin"],
  "scheduled_at": "2026-04-01T09:00:00Z",
  "media_ids": ["media_abc123"]
}

# 게시물 조회
GET /v1/posts/{id}

# 예약 게시물 취소
DELETE /v1/posts/{id}

미디어

# 미디어 업로드
POST /v1/media
Content-Type: multipart/form-data
# 반환: { "id": "media_abc123", "url": "...", "type": "image" }

# 미디어 라이브러리 목록
GET /v1/media?type=image&limit=50

플랫폼

# 연결된 채널 목록
GET /v1/platforms

# 채널 연결 해제
DELETE /v1/platforms/{id}

AI 생성

# 게시물 텍스트 생성
POST /v1/ai/text
{
  "prompt": "새 기능 발표: 다크 모드",
  "platform": "twitter",
  "tone": "casual"
}

# 이미지 생성
POST /v1/ai/image
{
  "prompt": "깔끔한 미니멀 데스크 셋업, 자연광",
  "size": "1024x1024"
}

자동화

# 자동화 목록
GET /v1/automations

# 자동화 수동 트리거
POST /v1/automations/{id}/trigger
{ "input": "https://example.com/article" }

웹훅

이벤트를 수신할 URL을 등록하세요:

POST /v1/webhooks
{
  "url": "https://yoursite.com/postclaw-events",
  "events": ["post.published", "post.failed", "automation.completed"]
}

이벤트 페이로드 구조:

{
  "event": "post.published",
  "timestamp": "2026-04-01T09:00:05Z",
  "data": {
    "post_id": "post_xyz789",
    "platform": "twitter",
    "url": "https://twitter.com/user/status/..."
  }
}

오류 응답

모든 오류는 일관된 형식을 따릅니다:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "요청이 너무 많습니다. 60초 후에 재시도하세요.",
    "retry_after": 60
  }
}

일반적인 오류 코드: unauthorized, forbidden, not_found, validation_error, rate_limit_exceeded, platform_error.

SDK

공식 SDK는 준비 중입니다. 지금은 HTTP 클라이언트를 직접 사용하세요. API는 app.postclaw.fun/docs에 완전히 문서화되어 있습니다(OpenAPI 3.1 스펙 다운로드 가능).