본문으로 건너뛰기

API 상세 명세

/api/v2로 시작하는 경로를 빼고는 아래 경로 앞에 기본 주소를 붙이세요. 작업에 따라 이용 가능한 요금제, 서비스 계정 연결, 기능 사용 권한도 필요합니다.

기본 주소

https://withseed.app/api/v1

표에서 (+ contexts:read)는 Context를 연결한 경우에만 필요합니다. /ai/text에서는 SEO 자동 수정에 seo:fix를, 다른 편집에 ai:edit를 사용합니다.

메서드경로필요한 권한
GET/me유효한 연결 또는 API 키
GET / POST/drafts · /notesdrafts:read / drafts:write
GET / PATCH / DELETE/drafts/{id}drafts:read / drafts:write
GET/api/v2/drafts/{id}/publishing-readinessdrafts:read + seo:score
GET / POST/contextscontexts:read / contexts:write
GET / PATCH / DELETE/contexts/{id}contexts:read / contexts:write
POST/contexts/{id}/refreshcontexts:write
POST/draft-setupsdrafts:write (+ contexts:read)
GET/draft-generation-runs/{id}drafts:read (+ contexts:read)
POST/draft-generation-runs/{id}/execute · /draft-generation-runs/{id}/retryai:draft + drafts:write (+ contexts:read)
POST/previewblogger:preview
POST/seo-scoreseo:score
POST/seo-fixseo:fix
POST/drafts/generate · /ai/draftai:draft
POST/ai/textai:edit / seo:fix
POST/ai/article-images · /images/generateai:image
POST/images/uploadimages:upload
GET/blogger/blogs · /blogger/operations/{key}blogger:read
POST/blogger/resolve-targetblogger:read
POST/blogger/save-draftblogger:draft
POST/blogger/publishblogger:publish
GET / POST / PATCH/drafts/{id}/promotion-packsocial:read / social:write
POST/drafts/{id}/promotion-pack/short-linksocial:write
GET / POST/social/destinationssocial:read / social:write
GET/social/publicationssocial:read
POST/social/publishsocial: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가 있으면 안전하게 다시 보낼 수 있습니다. 한 번 만들어 저장해 두고, 같은 본문을 다시 보낼 때만 같은 값을 쓰세요.

필드형식조건
creationRequestIdUUID필수
titlestring ≤ 200선택
contentMarkdown선택
keywordstring ≤ 100 | null선택
blogUrlURL | null선택
postLanguageBCP 47 | null선택
marketstring ≤ 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과 바꿀 필드만 보내세요.

필드형식조건
expectedVersioninteger ≥ 1필수
titlestring ≤ 200선택
contentMarkdown선택
keywordstring ≤ 100 | null선택
blogUrlURL | null선택
postLanguageBCP 47 | null선택
{ "expectedVersion": 3, "title": "A clearer title" }

DELETE /drafts/{id}

현재 버전의 초안을 삭제합니다.

필드형식조건
expectedVersioninteger ≥ 1필수
{ "expectedVersion": 4 }

POST /notes

고정된 원본 노트에 연결된 초안을 만듭니다. POST /drafts와 같은 필드에 sourceId를 더합니다.

필드형식조건
sourceIdstring ≤ 300필수
creationRequestIdUUID필수
titlestring ≤ 200선택
contentMarkdown선택
keywordstring ≤ 100 | null선택
blogUrlURL | null선택
postLanguageBCP 47 | null선택
marketstring ≤ 10선택
{ "sourceId": "vault/notes/launch.md", "creationRequestId": "…", "content": "Markdown body" }

POST /preview

Markdown을 Blogger에 보낼 HTML로 바꿉니다. 아무것도 저장하지 않습니다.

필드형식조건
contentMarkdown필수
{ "content": "## Heading

Markdown body" }

POST /seo-score

제목과 Markdown 본문을 목표 키워드 기준으로 채점합니다. 아무것도 저장하지 않습니다.

필드형식조건
contentMarkdown필수
titlestring ≤ 200선택
keywordstring ≤ 100선택
postLanguageBCP 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-Keystring ≤ 128헤더
contentMarkdown필수
titlestring필수
keywordstring필수
dimensionNametitleOptimization | keywordDensity | headingStructure | contentLength | aeoOptimization | empathyIntro필수
postLanguageBCP 47선택
{ "title": "How we built it", "content": "Markdown body", "keyword": "web app starter kit", "dimensionName": "titleOptimization" }

POST /images/generate

이미지 한 장을 만듭니다(Pro). prompt, title, content 중 하나 이상을 보내세요.

필드형식조건
Idempotency-Keystring ≤ 128헤더
promptstring ≤ 1000이 중 하나 이상
titlestring ≤ 200이 중 하나 이상
contentMarkdown이 중 하나 이상
altstring ≤ 160선택
styleminimal-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에는 아무것도 쓰지 않습니다.

필드형식조건
draftIdUUID필수
expectedDraftVersioninteger ≥ 1선택
blogIdstring선택
slugstring ≤ 60선택
labelsstring[] ≤ 50선택
allowCrossBlogDuplicateboolean선택
blogContextConfirmationobject선택
{ "draftId": "…", "expectedDraftVersion": 4, "blogId": "1234567890" }

POST /blogger/publish · /blogger/save-draft

초안을 발행하거나 Blogger 임시 글로 저장합니다. 먼저 대상을 확인하고 사용자 승인을 받으세요.

필드형식조건
Idempotency-Keystring헤더
draftIdUUID필수
expectedDraftVersioninteger ≥ 1필수
blogIdstring선택
slugstring ≤ 60선택
labelsstring[] ≤ 50선택
allowCrossBlogDuplicateboolean선택
blogContextConfirmationobject선택
{ "draftId": "…", "expectedDraftVersion": 4, "blogId": "1234567890", "labels": ["Guides"] }

AI가 안전하게 발행하는 순서

준비 상태, 사용자의 발행 승인, Blogger 발행 대상을 각각 확인하세요. READY_FOR_REVIEW가 나왔다는 이유만으로 발행하면 안 됩니다.

서로 다른 세 가지 정보

  • 블로그 문맥은 이 글의 주제와 설정을 따를 공개 블로그입니다. 참고 사이트일 수 있으며 발행 대상과 같지 않을 수 있습니다.
  • 글쓰기 프로필은 사용자의 글쓰기 취향을 제공합니다. API는 설정 여부만 알려주며 실제 값은 반환하지 않습니다.
  • Blogger 발행 대상은 글을 실제로 받을 연결된 블로그입니다. 별도로 확인하고 승인받아야 합니다.

먼저 설정할 정보

  • 최신 초안 버전에 제목, 본문, 블로그 문맥, 글 언어를 저장하세요. 키워드는 선택 사항이며, 없으면 SEO 점수를 매기지 않습니다.
  • 글쓰기 프로필을 설정하면 문체를 맞추는 데 도움이 되지만, 없어도 초안을 검토할 수 있습니다.
  • Blogger에 쓰기 전에 SEED에서 Blogger를 연결하고 발행 가능한 블로그를 선택하세요.
  • 읽기, 편집, 미리보기, 발행 작업마다 꼭 필요한 API 권한만 허용하세요.

발행 순서

  1. 최신 초안과 버전을 읽고 publishing-readiness를 조회하세요.
  2. 제목, 본문, 블로그 문맥이 빠졌다면 채우고 다시 확인하세요. SEO 점수와 글쓰기 프로필 안내는 참고 사항일 뿐, 글의 품질이나 발행 승인을 뜻하지 않습니다.
  3. Blogger 대상을 확인하고 사용자에게 발행 대상과 현재 초안 버전을 보여준 뒤 명확히 승인받으세요.
  4. Blogger 쓰기 요청 전에 최종 내용을 미리보기로 확인하세요.
  5. 요청 전에 저장한 새 Idempotency-Key와 expectedDraftVersion으로 발행하세요.
  6. 결과를 알 수 없으면 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 키, 인증 코드, 토큰, 비공개 노트 내용은 보내지 마세요.

도움 요청하기