API 상세 명세
/api/v2로 시작하는 경로를 빼고는 아래 경로 앞에 기본 주소를 붙이세요. 작업에 따라 이용 가능한 요금제, 서비스 계정 연결, 기능 사용 권한도 필요합니다.
기본 주소
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 | /api/v2/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 /api/v2/drafts/{id}/publishing-readiness를 조회하세요. 제목, 본문, 블로그 문맥이 빠지면 검토를 시작할 수 없습니다. 키워드가 없으면 점수를 매기지 않고, 낮은 SEO 점수는 참고 사항입니다. 사실 여부, 검색 성과, Blogger 발행 대상은 따로 확인해야 하며 이 응답은 발행 허가가 아닙니다.
요청 본문
Content-Type: application/json으로 JSON을 보내세요. 필드 이름은 응답과 같은 camelCase를 씁니다. 기존 클라이언트를 위해 초안 쓰기 요청은 예전 snake_case 이름(예: blog_url)도 받지만, 한 필드를 두 가지 이름으로 함께 보내면 안 됩니다. 모르는 필드는 거절됩니다.
POST /drafts
초안을 만듭니다. creationRequestId가 있으면 안전하게 다시 보낼 수 있습니다. 한 번 만들어 저장해 두고, 같은 본문을 다시 보낼 때만 같은 값을 쓰세요.
| 필드 | 형식 | 조건 |
|---|---|---|
| creationRequestId | UUID | 필수 |
| title | string ≤ 200 | 선택 |
| content | Markdown | 선택 |
| keyword | string ≤ 100 | null | 선택 |
| blogUrl | URL | null | 선택 |
| postLanguage | BCP 47 | null | 선택 |
| market | string ≤ 10 | 선택 |
{
"creationRequestId": "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b",
"title": "How we built it",
"content": "## Why
Markdown body",
"keyword": "web app starter kit",
"blogUrl": "https://blog.example.com/",
"postLanguage": "en"
}PATCH /drafts/{id}
초안을 수정합니다. 가장 최근에 조회한 expectedVersion과 바꿀 필드만 보내세요.
| 필드 | 형식 | 조건 |
|---|---|---|
| expectedVersion | integer ≥ 1 | 필수 |
| title | string ≤ 200 | 선택 |
| content | Markdown | 선택 |
| keyword | string ≤ 100 | null | 선택 |
| blogUrl | URL | null | 선택 |
| postLanguage | BCP 47 | null | 선택 |
{ "expectedVersion": 3, "title": "A clearer title" }DELETE /drafts/{id}
현재 버전의 초안을 삭제합니다.
| 필드 | 형식 | 조건 |
|---|---|---|
| expectedVersion | integer ≥ 1 | 필수 |
{ "expectedVersion": 4 }POST /notes
고정된 원본 노트에 연결된 초안을 만듭니다. POST /drafts와 같은 필드에 sourceId를 더합니다.
| 필드 | 형식 | 조건 |
|---|---|---|
| sourceId | string ≤ 300 | 필수 |
| creationRequestId | UUID | 필수 |
| title | string ≤ 200 | 선택 |
| content | Markdown | 선택 |
| keyword | string ≤ 100 | null | 선택 |
| blogUrl | URL | null | 선택 |
| postLanguage | BCP 47 | null | 선택 |
| market | string ≤ 10 | 선택 |
{ "sourceId": "vault/notes/launch.md", "creationRequestId": "…", "content": "Markdown body" }POST /preview
Markdown을 Blogger에 보낼 HTML로 바꿉니다. 아무것도 저장하지 않습니다.
| 필드 | 형식 | 조건 |
|---|---|---|
| content | Markdown | 필수 |
{ "content": "## Heading
Markdown body" }POST /seo-score
제목과 Markdown 본문을 목표 키워드 기준으로 채점합니다. 아무것도 저장하지 않습니다.
| 필드 | 형식 | 조건 |
|---|---|---|
| content | Markdown | 필수 |
| title | string ≤ 200 | 선택 |
| keyword | string ≤ 100 | 선택 |
| postLanguage | BCP 47 | 선택 |
{ "title": "How we built it", "content": "Markdown body", "keyword": "web app starter kit", "postLanguage": "en" }POST /seo-fix
SEO 항목 하나를 AI로 개선해, 제안된 제목이나 본문을 돌려줍니다. 저장은 하지 않습니다. 422 응답에는 고치지 못한 이유가 outcome으로 담깁니다. MANUAL_KEYWORD_PLACEMENT_REQUIRED는 H2/H3 제목이 이미 세 개 이상인데 정확한 키워드가 들어간 제목이 없다는 뜻이니, 키워드를 제목 하나에 직접 넣으세요.
| 필드 | 형식 | 조건 |
|---|---|---|
| Idempotency-Key | string ≤ 128 | 헤더 |
| content | Markdown | 필수 |
| title | string | 필수 |
| keyword | string | 필수 |
| dimensionName | titleOptimization | keywordDensity | headingStructure | contentLength | aeoOptimization | empathyIntro | 필수 |
| postLanguage | BCP 47 | 선택 |
{ "title": "How we built it", "content": "Markdown body", "keyword": "web app starter kit", "dimensionName": "titleOptimization" }POST /images/generate
이미지 한 장을 만듭니다(Pro). prompt, title, content 중 하나 이상을 보내세요.
| 필드 | 형식 | 조건 |
|---|---|---|
| Idempotency-Key | string ≤ 128 | 헤더 |
| prompt | string ≤ 1000 | 이 중 하나 이상 |
| title | string ≤ 200 | 이 중 하나 이상 |
| content | Markdown | 이 중 하나 이상 |
| alt | string ≤ 160 | 선택 |
| style | minimal-line | flat-illustration | 3d-clay | watercolor | retro-pixel | photoreal | 선택 |
{ "prompt": "Flat illustration of modular blocks, no text", "alt": "Modular blocks", "style": "flat-illustration" }POST /blogger/resolve-target
초안이 어느 Blogger 블로그와 글에 쓰일지 확인합니다. Blogger에는 아무것도 쓰지 않습니다.
| 필드 | 형식 | 조건 |
|---|---|---|
| draftId | UUID | 필수 |
| expectedDraftVersion | integer ≥ 1 | 선택 |
| blogId | string | 선택 |
| slug | string ≤ 60 | 선택 |
| labels | string[] ≤ 50 | 선택 |
| allowCrossBlogDuplicate | boolean | 선택 |
| blogContextConfirmation | object | 선택 |
{ "draftId": "…", "expectedDraftVersion": 4, "blogId": "1234567890" }POST /blogger/publish · /blogger/save-draft
초안을 발행하거나 Blogger 임시 글로 저장합니다. 먼저 대상을 확인하고 사용자 승인을 받으세요.
| 필드 | 형식 | 조건 |
|---|---|---|
| Idempotency-Key | string | 헤더 |
| draftId | UUID | 필수 |
| expectedDraftVersion | integer ≥ 1 | 필수 |
| blogId | string | 선택 |
| slug | string ≤ 60 | 선택 |
| labels | string[] ≤ 50 | 선택 |
| allowCrossBlogDuplicate | boolean | 선택 |
| blogContextConfirmation | object | 선택 |
{ "draftId": "…", "expectedDraftVersion": 4, "blogId": "1234567890", "labels": ["Guides"] }AI가 안전하게 발행하는 순서
준비 상태, 사용자의 발행 승인, Blogger 발행 대상을 각각 확인하세요. READY_FOR_REVIEW가 나왔다는 이유만으로 발행하면 안 됩니다.
서로 다른 세 가지 정보
- 블로그 문맥은 이 글의 주제와 설정을 따를 공개 블로그입니다. 참고 사이트일 수 있으며 발행 대상과 같지 않을 수 있습니다.
- 글쓰기 프로필은 사용자의 글쓰기 취향을 제공합니다. API는 설정 여부만 알려주며 실제 값은 반환하지 않습니다.
- Blogger 발행 대상은 글을 실제로 받을 연결된 블로그입니다. 별도로 확인하고 승인받아야 합니다.
먼저 설정할 정보
- 최신 초안 버전에 제목, 본문, 블로그 문맥, 글 언어를 저장하세요. 키워드는 선택 사항이며, 없으면 SEO 점수를 매기지 않습니다.
- 글쓰기 프로필을 설정하면 문체를 맞추는 데 도움이 되지만, 없어도 초안을 검토할 수 있습니다.
- Blogger에 쓰기 전에 SEED에서 Blogger를 연결하고 발행 가능한 블로그를 선택하세요.
- 읽기, 편집, 미리보기, 발행 작업마다 꼭 필요한 API 권한만 허용하세요.
발행 순서
- 최신 초안과 버전을 읽고 publishing-readiness를 조회하세요.
- 제목, 본문, 블로그 문맥이 빠졌다면 채우고 다시 확인하세요. SEO 점수와 글쓰기 프로필 안내는 참고 사항일 뿐, 글의 품질이나 발행 승인을 뜻하지 않습니다.
- Blogger 대상을 확인하고 사용자에게 발행 대상과 현재 초안 버전을 보여준 뒤 명확히 승인받으세요.
- Blogger 쓰기 요청 전에 최종 내용을 미리보기로 확인하세요.
- 요청 전에 저장한 새 Idempotency-Key와 expectedDraftVersion으로 발행하세요.
- 결과를 알 수 없으면 GET /blogger/operations/{key}를 확인하세요. 원래 결과를 알기 전에는 새 키로 다시 발행하지 마세요.
준비를 막는 항목과 nextStep
- TITLE_REQUIRED / CONTENT_REQUIRED
COMPLETE_DRAFT빠진 제목이나 본문을 넣고 저장한 뒤 새 버전을 확인하세요.- BLOG_CONTEXT_REQUIRED
SELECT_BLOG_CONTEXT어느 공개 블로그를 글의 문맥으로 쓸지 사용자에게 묻고 주소를 저장하세요.
블로그 문맥과 발행 대상이 다를 때
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 계약에 포함되지 않습니다.
초안이나 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 키, 인증 코드, 토큰, 비공개 노트 내용은 보내지 마세요.
도움 요청하기