API 상세 명세
아래 경로 앞에 기본 주소를 붙이세요. 작업에 따라 이용 가능한 요금제, 서비스 계정 연결, 기능 사용 권한도 필요합니다.
기본 주소
https://withseed.app/api/v1표에서 (+ contexts:read)는 Context를 연결한 경우에만 필요합니다. /ai/text에서는 SEO 자동 수정에 seo:fix를, 다른 편집에 ai:edit를 사용합니다.
| 메서드 | 경로 | 필요한 권한 |
|---|---|---|
| GET | /me | 유효한 연결 또는 API 키 |
| GET / POST | /drafts · /notes | drafts:read / drafts:write |
| GET / PATCH / DELETE | /drafts/{id} | drafts:read / drafts:write |
| GET | /drafts/{id}/publishing-readiness | drafts:read + seo:score |
| GET / POST | /contexts | contexts:read / contexts:write |
| GET / PATCH / DELETE | /contexts/{id} | contexts:read / contexts:write |
| POST | /contexts/{id}/refresh | contexts:write |
| POST | /draft-setups | drafts:write (+ contexts:read) |
| GET | /draft-generation-runs/{id} | drafts:read (+ contexts:read) |
| POST | /draft-generation-runs/{id}/execute · /draft-generation-runs/{id}/retry | ai:draft + drafts:write (+ contexts:read) |
| POST | /preview | blogger:preview |
| POST | /seo-score | seo:score |
| POST | /seo-fix | seo:fix |
| POST | /drafts/generate · /ai/draft | ai:draft |
| POST | /ai/text | ai:edit / seo:fix |
| POST | /ai/article-images · /images/generate | ai:image |
| POST | /images/upload | images:upload |
| GET | /blogger/blogs · /blogger/operations/{key} | blogger:read |
| POST | /blogger/resolve-target | blogger:read |
| POST | /blogger/save-draft | blogger:draft |
| POST | /blogger/publish | blogger:publish |
| GET / POST / PATCH | /drafts/{id}/promotion-pack | social:read / social:write |
| POST | /drafts/{id}/promotion-pack/short-link | social:write |
| GET / POST | /social/destinations | social:read / social:write |
| GET | /social/publications | social:read |
| POST | /social/publish | social:publish |
| GET / POST | /social/schedules · /social/schedules/{id} | social:read / social:publish |
발행 전에는 drafts:read와 seo:score 권한으로 GET /drafts/{id}/publishing-readiness를 조회하세요. 80점 이상은 저장된 초안을 발행 검토할 수 있다는 뜻일 뿐, 발행 허가가 아니며 Blogger 대상도 확인하지 않습니다.
AI가 안전하게 발행하는 순서
준비 상태, 사용자의 발행 승인, Blogger 발행 대상을 각각 확인하세요. READY_FOR_REVIEW가 나왔다는 이유만으로 발행하면 안 됩니다.
서로 다른 세 가지 정보
- 블로그 문맥은 이 글의 주제와 설정을 따를 공개 블로그입니다. 참고 사이트일 수 있으며 발행 대상과 같지 않을 수 있습니다.
- 글쓰기 프로필은 사용자의 글쓰기 취향을 제공합니다. API는 설정 여부만 알려주며 실제 값은 반환하지 않습니다.
- Blogger 발행 대상은 글을 실제로 받을 연결된 블로그입니다. 별도로 확인하고 승인받아야 합니다.
먼저 설정할 정보
- 최신 초안 버전에 제목, 본문, 핵심 키워드, 블로그 문맥, 글 언어를 저장하세요.
- 글 언어에 맞는 기본 글쓰기 프로필이나 정확한 블로그 문맥용 프로필을 설정하세요.
- Blogger에 쓰기 전에 SEED에서 Blogger를 연결하고 발행 가능한 블로그를 선택하세요.
- 읽기, 편집, 미리보기, 발행 작업마다 꼭 필요한 API 권한만 허용하세요.
발행 순서
- 최신 초안과 버전을 읽고 publishing-readiness를 조회하세요.
- 모든 blocker를 해결하고 글이나 설정이 바뀔 때마다 준비 상태를 다시 조회하세요. 80점 이상은 검토 시작 기준이지 발행 승인이 아닙니다.
- Blogger 대상을 확인하고 사용자에게 발행 대상과 현재 초안 버전을 보여준 뒤 명확히 승인받으세요.
- Blogger 쓰기 요청 전에 최종 내용을 미리보기로 확인하세요.
- 요청 전에 저장한 새 Idempotency-Key와 expectedDraftVersion으로 발행하세요.
- 결과를 알 수 없으면 GET /blogger/operations/{key}를 확인하세요. 원래 결과를 알기 전에는 새 키로 다시 발행하지 마세요.
준비를 막는 항목과 nextStep
- TITLE_REQUIRED / CONTENT_REQUIRED
COMPLETE_DRAFT빠진 제목이나 본문을 넣고 저장한 뒤 새 버전을 확인하세요.- KEYWORD_REQUIRED
SET_KEYWORD글의 핵심 키워드를 정해 저장하고 다시 평가하세요.- BLOG_CONTEXT_REQUIRED
SELECT_BLOG_CONTEXT어느 공개 블로그를 글의 문맥으로 쓸지 사용자에게 묻고 주소를 저장하세요.- WRITING_PROFILE_REQUIRED
CONFIGURE_WRITING_PROFILE사용자에게 SEED 설정에서 글쓰기 프로필을 설정해 달라고 요청하세요.- SEO_BELOW_REVIEW_THRESHOLD
IMPROVE_SEO_AND_RECHECK글을 개선해 저장한 뒤 새 점수를 요청하세요.
블로그 문맥과 발행 대상이 다를 때
409 BLOG_CONTEXT_TARGET_MISMATCH가 나오면 Blogger에 글을 쓰기 전에 요청이 멈춥니다. expectedBlogUrl과 사용자가 고른 Blogger URL을 보여주세요. 확인 뒤 새 Idempotency-Key와 blogId=chosenBlog.id로 요청하세요. blogContextConfirmation은 error.confirmation의 draftId, draftVersion, expectedBlogUrl에 selectedBlogId=chosenBlog.id를 넣어 만듭니다. 이 확인에 allowCrossBlogDuplicate를 쓰면 안 됩니다.
멈추고 사용자에게 물어볼 때
- blocker가 남았거나 초안 버전이 바뀌었거나 발행 대상이 없거나 분명하지 않습니다.
- 블로그 문맥과 발행 대상이 다른데 사용자가 정확한 대상을 확인하지 않았습니다.
- 미리보기에 예상하지 못한 개인정보, 근거 없는 주장, 사용자가 승인하지 않은 내용이 있습니다.
- 발행 결과를 알 수 없거나 인증이 만료됐거나 서비스 연결을 다시 해야 합니다.
절대 필요하지 않은 정보
API 키, 접근 토큰, 인증 코드, 비공개 노트, 프로필 실제 값을 요청하거나 저장·기록·발행하지 마세요. SEED의 점수 계산식, 내부 프롬프트, 부정 사용 방지 방식, 비공개 사업 규칙은 공개 API 계약에 포함되지 않습니다.
초안을 수정하거나 삭제할 때는 현재 expected_version이 필요합니다. Context 수정은 expectedVersion, Blogger 저장·발행은 expectedDraftVersion을 사용합니다. 바꾸기 전에 최신 내용을 조회하세요.
AI, 이미지, Context 생성, 글 생성 설정, Blogger 쓰기, SNS 작업은 API가 요구하는 경우 고정된 Idempotency-Key가 필요합니다. 쓰기 요청 전에 키를 저장하고 같은 작업·같은 내용에만 다시 사용하세요.
발행 결과를 모를 때는 원래 작업 키를 보관하고 상태부터 확인하세요. 새 키를 만들어 강제로 다시 발행하지 마세요. Blogger 결과는 GET /blogger/operations/{key}에서 확인할 수 있습니다.
선택할 수 있는 권한
- drafts:read
- 초안 읽기
- drafts:write
- 초안 만들기·수정·삭제
- contexts:read
- Context 읽기
- contexts:write
- Context 만들기·수정·삭제
- blogger:read
- Blogger 블로그와 발행 결과 읽기
- blogger:preview
- Blogger HTML 미리보기
- blogger:draft
- Blogger 초안 저장
- blogger:publish
- Blogger 글 발행·수정
- seo:score
- SEO 평가
- seo:fix
- AI로 SEO 개선
- ai:draft
- AI로 초안·개요 만들기
- ai:edit
- AI로 편집·번역
- ai:image
- AI 이미지 만들기
- images:upload
- 이미지 업로드
- social:read
- SNS 홍보 묶음과 발행 결과 읽기
- social:write
- SNS 홍보 묶음 만들기·수정
- social:publish
- SNS 글 발행·예약
도움이 필요한가요?
요청한 경로, HTTP 상태, 오류 코드, 대략적인 요청 시각을 알려주세요. API 키, 인증 코드, 토큰, 비공개 노트 내용은 보내지 마세요.
도움 요청하기